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

▶ 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.

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 [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) — pac