com.codician/growmos

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

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

CLI	growmos init --agent … writes	How the agent uses it
Claude Code	CLAUDE.md block, .claude/skills/growmos/SKILL.md, SessionStart/Stop hooks in .claude/settings.json, .mcp.json	context injected at session start; skill triggers on graph-related asks; MCP tools
Codex CLI	AGENTS.md block (+ optional MCP server)	Codex reads AGENTS.md; run growmos mcp as an MCP server if you prefer tools
Grok CLI / others	AGENTS.md block, .mcp.json	any CLI honouring AGENTS.md or MCP
Cursor	.cursor/rules/growmos.mdc (alwaysApply)	rules loaded in every chat
Gemini CLI	GEMINI.md block	same protocol
Any file	growmos integrate file --file path/to/instructions.md	append the protocol block anywhere
git	growmos integrate hooks → post-commit, post-merge, post-checkout	queue changed docs automatically
CI	growmos integrate ci → .github/workflows/growmos.yml	doctor + eval on every PR
MCP	growmos integrate mcp → .mcp.json (+ .cursor/mcp.json)	tools for any MCP client (below)

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"]
    }
  }
}

Client	Where
Claude Code	.mcp.json in the repo (written by growmos init / integrate claude), or claude mcp add growmos -- growmos mcp
Cursor	.cursor/mcp.json (written by integrate cursor / integrate mcp)
Codex CLI	~/.codex/config.toml: [mcp_servers.growmos] command = "growmos" args = ["mcp"]
Gemini CLI	~/.gemini/settings.json → mcpServers.growmos as above
Grok CLI / others	their MCP config, same JSON

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.

What lives in .growmos/ (commit it)

.growmos/
  config.json       include globs, caps (max_docs_per_run, max_entities_per_doc), provider
  schema.json       versioned entity types + predicate hints (bump on change; rows carry schema_version)
  state.json        the loop's state file: runs, pending re-summarizations, last sample/eval
  sources.jsonl     every document eaten: ref, sha256, status (pending|extracted|note|missing)
  mentions.jsonl    raw per-document extraction output (append-only provenance)
  entities.jsonl    canonical nodes (id, name, type, description, sources, mentions, provisional)
  aliases.jsonl     alias → entity (the alias map)
  relations.jsonl   edges: source, predicate, target, sources[], confidence (= corroborating docs)
  profiles/*.json   hub-node profiles (summary, key facts, time range), keyed to source-set hash
  prompts/*.md      the four playbook prompts + evaluator prompt — yours to tune
  eval/gold/*.json  hand-labelled gold sets · eval/aliases.json scorer alias map
  journal.md        the shared memo, append-only

Plain JSONL: diff-able, merge-friendly, greppable, viewable (growmos view) and exportable (growmos export --format html|json|dot|mermaid|cypher|sql). Storage is an infrastructure decision, not a pipeline decision: the same schema maps onto Neo4j or three Postgres tables.

Configuration & big projects

Everything tunable lives in .growmos/config.json (growmos config <key> [value]). Defaults are sized for a normal repo; for a big one, three knobs matter:

• max_docs_per_run (default 50/day) — a speed bump against runaway unattended runs, not a wall. When you or your agent are driving a backfill: growmos next --force or growmos config max_docs_per_run 0. Agents are told this, so they won't stall on it.
• include / exclude — which docs are knowledge (READMEs, ADRs, design docs by default; never source code — agents write what code means via remember/link).
• chunk_chars (6 000) — packet size for long documents.

Full reference (all keys, monorepos, cost notes): docs/configuration.md.

Presets

growmos init --preset software|general|research|business — same prompts, extended entity vocabulary (the playbook's five base types + domain types). growmos remember --type NEWTYPE extends the schema on the fly (schema version bumps).

Headless / overnight mode (optional)

export ANTHROPIC_API_KEY=…    # or OPENAI_API_KEY / XAI_API_KEY, or GROWMOS_PROVIDER + GROWMOS_BASE_URL
growmos ingest --scan          # extraction (fast model) → resolution → profiles (reasoning model)
growmos query "…" --auto

Follows the playbook's model split (a fast model for high-volume extraction, a stronger model for judgment). Cap runs with max_docs_per_run (default 50/day; growmos next --force or growmos config max_docs_per_run 0 when you're driving a big backfill). Prompt caching and batching are the natural next optimizations for large corpora.

Operational discipline (baked in)

• Sample the graph — growmos sample (doctor warns after 7 days).
• Cap extraction volume — max_docs_per_run (50/day; a speed bump, not a wall: growmos next --force, or growmos config max_docs_per_run 0 for a big backfill), max_entities_per_doc.
• Version the schema — growmos schema bump --note … --add-type ….
• Never lose a name — unmatched names get single-element clusters.
• Every edge has provenance — and a corroboration count.
• Re-summarize only when the source set changes — profiles carry a source-set hash.
• Watch connectivity & density — growmos status prints components / density / compression.

Docs

• METHODOLOGY.md — the living-knowledge-graph methodology, tool-agnostic
• docs/agents.md — per-CLI setup and the agent protocol
• docs/file-format.md — store layout & JSON shapes
• docs/evaluation.md — gold sets, scoring, prompt tuning loop
• docs/configuration.md — every config key, big projects, monorepos
• docs/headless.md — provider mode, cron, CI
• examples/apollo — the playbook's Apollo corpus rebuilt in one script

Contributing

PRs welcome — see CONTRIBUTING.md. Run python -m unittest discover -s tests.

MIT © 2026 Codician. Not affiliated with Anthropic; the methodology it implements is a synthesis of Anthropic's public knowledge-graph cookbook and agent-pattern writing.