growmos

A living knowledge graph that grows with your repo. Shared, provenance-carrying memory for humans and AI agents — plug & play with Claude Code, Codex, Grok, Cursor, Gemini, or any MCP-capable CLI. Zero dependencies. MIT.

"Each agent's memory dies with its context window." growmos is the layer underneath: the durable, queryable world model that lets today's session pick up where yesterday's left off — and lets five agents share one picture of the codebase without passing it through anyone's context window.

Built by Codician as an open, tool-agnostic implementation of the knowledge-graph methodology described in Knowledge Graph Engineering for Multi-Agentic Systems: The Anthropic Playbook (extraction → resolution → assembly → querying, with an evaluation loop closing the circle). See METHODOLOGY.md for the full methodology.

   docs, ADRs, READMEs, sessions ──▶ 1. Extraction ──▶ 2. Resolution ──▶ 3. Assembly ──▶ 4. Querying
                                     (agent packet)    (agent packet)    (deterministic)  (grounded answers,
                                                                                            edge citations)
                     ▲                                                                            │
                     └──────────────── growmos remember / link / journal  ◀── agents develop ◀────┘
                                       evaluation loop: change prompt → growmos eval → watch F1 move

▶ Live demo — click around growmos's own graph · Apollo corpus demo · site

growmos view — after a few days of development, this is what lays in your graph: hubs sized by degree, colored by type, every edge with provenance, profiles on click.

Why

Multi-agent systems and long-running coding sessions share one weakness: memory dies with the context window. RAG surfaces chunks but cannot chain facts. A knowledge graph — entities as nodes, short-verb-phrase relations as edges, every edge carrying provenance — turns multi-hop questions ("what depends on the thing we replaced in ADR-7, and who owns it?") into graph traversal, gives evaluators ground truth instead of vibes, and survives restarts.

growmos makes that a living organism inside your repo:

• It eats what you write. Docs, ADRs, READMEs, design notes, sessions. Content-hashed; only what changed goes back into the pipeline (incremental by construction).
• It grows as agents develop. growmos remember / link / journal are one-line write paths with provenance (session:2026-08-17). Git hooks queue changed docs after every commit.
• It resolves itself. New names are matched against the canonical set; unmatched names become provisional single-element clusters (nothing is ever silently lost); the agent then clusters provisional entities using descriptions ("Edwin Aldrin" → "Buzz Aldrin").
• It answers with citations. growmos query serializes the k-hop subgraph around a question; the answer must cite edge ids; growmos check fact-checks claims against edges.
• It measures itself — with no manual step. growmos next also hands out gold-set packets (the agent writes the reference answer from the source document) and periodic review packets (verify one node's edges against its sources), so growmos eval (P/R/F1, raw and resolved), the 10-item growmos doctor checklist and the health signals (components, density, compression) all stay green on autopilot. Every gold file records who reviewed it (agent / human) — humans can overrule at any time, but never have to.
• It shows itself. growmos view opens a self-contained, offline interactive explorer (force layout, search, type filters, click a node for its profile, edges and provenance) — no server, no dependencies. growmos export --format html|json|dot|mermaid|cypher|sql for everything else.
• It is agent-native. No API key needed: the CLI does the deterministic work, and hands the judgment work (extraction, resolution, summarization) to whatever agent you already run as a task packet — prompt + JSON shape + the exact growmos apply … command. Optional headless mode (growmos ingest) calls Anthropic / OpenAI-compatible / xAI APIs for cron & CI.

Install

pip install growmos          # or: pipx install growmos / uv tool install growmos

Python ≥ 3.9, no dependencies. (From source: pip install .)

60-second start

cd your-repo
growmos init                 # creates .growmos/, detects your agent CLI, wires it, scans docs
growmos next                 # → first task packet (extraction of README.md)

From here it runs itself:

• Claude Code (hooks): at session start the brief is injected and, if work is pending, the agent is told to run the loop; at the end of a turn a Stop hook scans your docs and, if new packets appeared, keeps the agent going until the graph is up to date and journaled. You never have to ask.
• Codex / Grok / Cursor / Gemini (no hooks): the same protocol lives in AGENTS.md / .cursor/rules — "if the brief shows pending work, run the loop before you stop." Agents follow it; you can still say "grow the knowledge graph" or "what does the graph say about X?".
• Nobody at the keyboard: git hooks queue changed docs after every commit, and growmos ingest on cron/CI (headless mode) does the whole loop with an API key.

Manually, the loop is:

growmos next                                 # packet: prompt + shape + apply command
#   … agent produces the JSON …
growmos apply extraction out.json --source src_ab12 --chunk 0
growmos next                                 # → resolution → profiles → gold set → review → "up to date"
growmos query "what depends on the Store and who decided that?"
growmos remember "Scheduler" --type COMPONENT --desc "Schedules jobs; depends on Store."
growmos link "Scheduler" "depends on" "Store"
growmos journal "Moved Store to Postgres (ADR-001)."
growmos check "(Alice Chen) --[owns]--> (Scheduler)"
growmos view                                 # open the interactive explorer in your browser
growmos status · growmos context · growmos doctor · growmos eval · growmos sample

Plug & play with agent CLIs

growmos init --agent all does all of the above. Everything is idempotent (marker blocks, JSON merges).

MCP server (any MCP-capable client)

growmos mcp is a zero-dependency MCP stdio server. Register it the same way you register any MCP server — growmos integrate mcp writes this for you, or paste it yourself:

{
  "mcpServers": {
    "growmos": {
      "command": "growmos",
      "args": ["mcp"]
    }
  }
}

mcp-name: com.codician/growmos

Tools exposed: growmos_context, growmos_query, growmos_entity, growmos_search, growmos_remember, growmos_link, growmos_journal, growmos_check, growmos_next, growmos_apply, growmos_status, growmos_sample. Once registered, the agent calls them directly instead of shelling out — e.g. "what depends on the Store?" → growmos_query; "remember that Scheduler now uses Kafka" → growmos_remember + growmos_link; "grow the graph" → growmos_next / growmos_apply in a loop.

Read the full README on GitHub →