JAMO.Cognita 0.14.1

Cognita

By JAMOLabs

Cognita builds a deterministic, source-linked semantic knowledge graph for .NET repositories and answers orientation and navigation questions from it — so humans (and coding agents) can understand a codebase without reading it file by file.

cognita extract <repo_path> --out facts
cognita summarize repo facts
cognita map architecture facts

New to a repository you just inherited? Start with the onboarding playbook.

Install

Cognita ships as a .NET global tool (requires the .NET 8 SDK or later).

From NuGet.org (once the package is published there):

dotnet tool install --global JAMO.Cognita

From a GitHub release asset (download the .nupkg from the latest release into a folder):

dotnet tool install --global JAMO.Cognita --add-source <folder-with-nupkg>

Either way, the installed command is cognita.

Check the installed tool and fact schema version:

cognita version

Releases are tag-driven: pushing a v<version> tag builds, tests, packs, and publishes the tool package. The package version always equals the fact schema version. Publishing to NuGet.org uses Trusted Publishing (OIDC — no stored API key); see PUBLISHING.md for the one-time setup and release checklist.

Snapshots

A facts directory plus its snapshot.json manifest is Cognita's portable snapshot unit. The manifest records a deterministic snapshot identity — a content hash over the semantic fact files (nodes, edges, properties, locations) — along with the schema version, repository id, commit hash, and fact counts. Contexts, metadata, and the error log sit outside the identity boundary: they may differ between runs or machines without changing what the snapshot is.

cognita snapshot create facts        # write snapshot.json
cognita snapshot info facts          # print identity + compatibility
cognita snapshot verify facts        # detect tampering/drift against the manifest
cognita snapshot export facts s.zip  # archive the snapshot for transfer
cognita snapshot import s.zip dir    # extract + verify a transferred snapshot

Compatibility follows the schema version: equal versions are exact, a differing patch is compatible, and any other difference is incompatible (pre-1.0 the schema evolves per minor version).

Structural diff

cognita diff <old_facts_dir> <new_facts_dir> compares two snapshots of the same repository and reports what changed structurally: added/removed entrypoints (including minimal-API routes), wiring changes (DI registrations, hosted services, options, DbContexts), intent changes, architecture-edge changes with occurrence shifts, hotspot shifts, and added/removed nodes — each with source evidence where available.

Comparison uses the snapshot identity boundary: the path-derived repository id is canonicalized (snapshots from different paths or machines compare cleanly), machine/run metadata is excluded, and path-hashed sub-structural nodes (lambdas, anonymous types) are ignored.

cognita extract <repo> --out facts-before
# ...make changes...
cognita extract <repo> --out facts-after
cognita diff facts-before facts-after

Structural diff in CI

--format markdown renders the diff for PR comments and job summaries, and --exit-code turns it into a build signal: 0 = no structural changes, 2 = changes found, 1 = error.

cognita diff facts-before facts-after --format markdown --exit-code

The composite action in .github/actions/cognita-diff wires this into a pull request: it extracts the base ref (via a git worktree) and the head checkout, diffs them, writes the job summary, and posts — or updates — a single PR comment. Cognita dogfoods it on its own pull requests (see .github/workflows/cognita-diff.yml).

- uses: actions/checkout@v4
  with:
    fetch-depth: 0          # base ref must be reachable
- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: "8.0.x"
- uses: nasmulla828-ai/Cognita/.github/actions/cognita-diff@master
  with:
    repo-path: .            # repository to analyse
    # base-ref: <sha>       # defaults to the PR base
    # source: release       # or "local" to build the tool from the checkout
    # fail-on-changes: true # gate the build on structural change

Requires pull-requests: write permission when commenting.

Architecture governance

Declare the layering your architecture is supposed to have, and Cognita enforces it against what the code actually does. Rules live in cognita.rules.json:

{
  "version": 1,
  "rules": [
    {
      "id": "web-must-not-touch-data",
      "description": "Presentation must not reach the data layer directly",
      "from": "*.Web",
      "to": "*.Data",
      "edges": ["calls", "data"],
      "allow": ["Legacy.Web"],
      "severity": "error"
    }
  ]
}

• from / to match project names, with * as a wildcard.
• edges limits which interactions count: calls, types, data, events, references (all of them when omitted).
• allow exempts specific source projects, for grandfathering existing debt.
• severity is error (fails) or warn (reported only) — adopt a rule as a warning first, then promote it.

cognita check facts                      # uses ./cognita.rules.json
cognita check facts --rules team.json --format markdown

Exit codes: 0 = clean or warnings only, 2 = error-severity violations, 1 = error. Violations name the offending project pair, the interaction count, and real call sites:

ERROR web-must-not-touch-data:
  - Nop.Web -> Nop.Data [PROJECT_CALLS] 27 occurrence(s)
  - Rule: Presentation must not reach the data layer directly
  - ProductController CALLS GetProductById at src/Presentation/Nop.Web/Controllers/ProductController.cs:214

The CI action runs the check automatically when a cognita.rules.json is present and folds the findings into the same PR comment as the structural diff. Cognita enforces its own layering this way — see cognita.rules.json.

MCP server (AI agents)

cognita mcp <facts_dir> starts a stdio MCP server over an extracted fact set, so coding agents can consult the graph directly. Exposed tools: summarize_repo, summarize_project, map_architecture, entrypoints, callers, callees, impact, explain, find_symbol, and query (pipe DSL, supported natural-language phrases, or structured phrases — natural language is compiled deterministically and the translation is included in the answer). Payloads are ranked, capped, and source-linked, matching the CLI's curation.

Example client registration (Claude Code):

claude mcp add cognita -- cognita mcp <facts_dir>

Benchmarks & evals

Real-repository benchmarks (extraction determinism, integrity, timing) and golden-answer orientation evals live under bench/ — see bench/README.md. Regressions there block merge, same as the test harness.

A standalone browser viewer lives in viewer/ — open viewer/index.html and load a facts folder to explore the graph visually, starting from the project-level flow map.

Composable queries

cognita query accepts natural-language-like query phrases, a deterministic pipe-based graph query language, and the existing callers, callees, impact, and other query phrases.

Natural-language-like queries are compiled to the pipe DSL first, then executed. The CLI prints the generated DSL to stderr so the translation stays inspectable.

cognita query facts "what does OrderService call"

cognita query facts "who implements IOrderService"

cognita query facts "show classes related to orders in project Nop.Web"

cognita query facts "which projects does Nop.Web call into most"

cognita query facts "entities touched by services"

Supported natural-language patterns include common symbol relationships (callers, callees, implements, inherits, event publishers/handlers), node searches (classes, interfaces, methods, controllers, services, entities, entrypoints), project calls/dependencies, and service/entity touches. It is intentionally deterministic rather than arbitrary English.

cognita query facts "nodes | where type = Interface and name contains \"Order\" | incoming IMPLEMENTS | select name,type,relationship,path | limit 25"

cognita query facts "symbol \"OrderPlacedEvent\" | both PUBLISHES_EVENT,HANDLES_EVENT | select name,relationship,source,target,occurrences | order by occurrences desc | limit 50"

cognita query facts "project \"Nop.Web\" | outgoing PROJECT_CALLS | select name,relationship,occurrences | order by occurrences desc | limit 10"

Sources:

• nodes
• edges
• symbol "<name>"
• project "<name>"

Pipeline stages:

• where <field> =|!=|contains|starts with <value>; join filters with and
• incoming, outgoing, or both followed by comma-separated edge types
• select followed by comma-separated fields
• order by <field> [asc|desc]
• limit <1-1000>

Fields include name, type, relationship, source, target, path, line, project, intent, occurrences, IDs, and property.<PropertyKey>. Projected rows retain node/edge IDs and source evidence in JSON and JSONL output.

License

Cognita is proprietary software. © JAMOLabs. See LICENSE.txt for the terms under which the compiled tool may be installed and used. For licensing inquiries, visit jamolabs.ai.