{ "markdown": "# growmos\n\n

\n \"PyPI\"\n \"CI\"\n \"Python\"\n \"MIT\"\n \"zero\n

\n\n**A living knowledge graph that grows with your repo.**\nShared, 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.\n\n> *\"Each agent's memory dies with its context window.\"* growmos is the layer underneath: the\n> durable, queryable world model that lets today's session pick up where yesterday's left off —\n> and lets five agents share one picture of the codebase without passing it through anyone's\n> context window.\n\nBuilt by [Codician](https://codician.com) as an open, tool-agnostic implementation of the\nknowledge-graph methodology described in *Knowledge Graph Engineering for Multi-Agentic Systems:\nThe Anthropic Playbook* (extraction → resolution → assembly → querying, with an evaluation loop\nclosing the circle). See [METHODOLOGY.md](METHODOLOGY.md) for the full methodology.\n\n```\n docs, ADRs, READMEs, sessions ──▶ 1. Extraction ──▶ 2. Resolution ──▶ 3. Assembly ──▶ 4. Querying\n (agent packet) (agent packet) (deterministic) (grounded answers,\n edge citations)\n ▲ │\n └──────────────── growmos remember / link / journal ◀── agents develop ◀────┘\n evaluation loop: change prompt → growmos eval → watch F1 move\n```\n\n

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

\n

\"growmos

\n

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.

\n\n## Why\n\nMulti-agent systems and long-running coding sessions share one weakness: memory dies with the\ncontext window. RAG surfaces chunks but cannot *chain* facts. A knowledge graph — entities as\nnodes, short-verb-phrase relations as edges, every edge carrying provenance — turns multi-hop\nquestions (\"what depends on the thing we replaced in ADR-7, and who owns it?\") into graph\ntraversal, gives evaluators ground truth instead of vibes, and survives restarts.\n\ngrowmos makes that a **living organism inside your repo**:\n\n- **It eats what you write.** Docs, ADRs, READMEs, design notes, sessions. Content-hashed;\n only what changed goes back into the pipeline (incremental by construction).\n- **It grows as agents develop.** `growmos remember` / `link` / `journal` are one-line write\n paths with provenance (`session:2026-08-17`). Git hooks queue changed docs after every commit.\n- **It resolves itself.** New names are matched against the canonical set; unmatched names\n become *provisional* single-element clusters (nothing is ever silently lost); the agent then\n clusters provisional entities using descriptions (\"Edwin Aldrin\" → \"Buzz Aldrin\").\n- **It answers with citations.** `growmos query` serializes the k-hop subgraph around a\n question; the answer must cite edge ids; `growmos check` fact-checks claims against edges.\n- **It measures itself — with no manual step.** `growmos next` also hands out *gold-set* packets\n (the agent writes the reference answer from the source document) and periodic *review*\n packets (verify one node's edges against its sources), so `growmos eval` (P/R/F1, raw and\n resolved), the 10-item `growmos doctor` checklist and the health signals (components, density,\n compression) all stay green on autopilot. Every gold file records who reviewed it\n (`agent` / `human`) — humans can overrule at any time, but never have to.\n- **It shows itself.** `growmos view` opens a self-contained, offline interactive explorer\n (force layout, search, type filters, click a node for its profile, edges and provenance) —\n no server, no dependencies. `growmos export --format html|json|dot|mermaid|cypher|sql` for\n everything else.\n- **It is agent-native.** No API key needed: the CLI does the deterministic work, and hands the\n *judgment* work (extraction, resolution, summarization) to whatever agent you already run as\n a **task packet** — prompt + JSON shape + the exact `growmos apply …` command. Optional\n headless mode (`growmos ingest`) calls Anthropic / OpenAI-compatible / xAI APIs for cron & CI.\n\n## Install\n\n```bash\npip install growmos # or: pipx install growmos / uv tool install growmos\n```\n\nPython ≥ 3.9, no dependencies. (From source: `pip install .`)\n\n## 60-second start\n\n```bash\ncd your-repo\ngrowmos init # creates .growmos/, detects your agent CLI, wires it, scans docs\ngrowmos next # → first task packet (extraction of README.md)\n```\n\nFrom here it runs itself:\n\n- **Claude Code** (hooks): at session start the brief is injected and, if work is pending, the\n agent is told to run the loop; at the end of a turn a `Stop` hook scans your docs and, if new\n packets appeared, keeps the agent going until the graph is up to date and journaled. You never\n have to ask.\n- **Codex / Grok / Cursor / Gemini** (no hooks): the same protocol lives in `AGENTS.md` /\n `.cursor/rules` — \"if the brief shows pending work, run the loop before you stop.\" Agents follow\n it; you *can* still say *\"grow the knowledge graph\"* or *\"what does the graph say about X?\"*.\n- **Nobody at the keyboard:** git hooks queue changed docs after every commit, and `growmos ingest`\n on cron/CI (headless mode) does the whole loop with an API key.\n\nManually, the loop is:\n\n```bash\ngrowmos next # packet: prompt + shape + apply command\n# … agent produces the JSON …\ngrowmos apply extraction out.json --source src_ab12 --chunk 0\ngrowmos next # → resolution → profiles → gold set → review → \"up to date\"\ngrowmos query \"what depends on the Store and who decided that?\"\ngrowmos remember \"Scheduler\" --type COMPONENT --desc \"Schedules jobs; depends on Store.\"\ngrowmos link \"Scheduler\" \"depends on\" \"Store\"\ngrowmos journal \"Moved Store to Postgres (ADR-001).\"\ngrowmos check \"(Alice Chen) --[owns]--> (Scheduler)\"\ngrowmos view # open the interactive explorer in your browser\ngrowmos status · growmos context · growmos doctor · growmos eval · growmos sample\n```\n\n## Plug & play with agent CLIs\n\n| CLI | `growmos init --agent …` writes | How the agent uses it |\n|---|---|---|\n| **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 |\n| **Codex CLI** | `AGENTS.md` block (+ optional MCP server) | Codex reads AGENTS.md; run `growmos mcp` as an MCP server if you prefer tools |\n| **Grok CLI / others** | `AGENTS.md` block, `.mcp.json` | any CLI honouring AGENTS.md or MCP |\n| **Cursor** | `.cursor/rules/growmos.mdc` (alwaysApply) | rules loaded in every chat |\n| **Gemini CLI** | `GEMINI.md` block | same protocol |\n| **Any file** | `growmos integrate file --file path/to/instructions.md` | append the protocol block anywhere |\n| **git** | `growmos integrate hooks` → `post-commit`, `post-merge`, `post-checkout` | queue changed docs automatically |\n| **CI** | `growmos integrate ci` → `.github/workflows/growmos.yml` | doctor + eval on every PR |\n| **MCP** | `growmos integrate mcp` → `.mcp.json` (+ `.cursor/mcp.json`) | tools for any MCP client (below) |\n\n`growmos init --agent all` does all of the above. Everything is idempotent (marker blocks, JSON merges).\n\n### MCP server (any MCP-capable client)\n\n`growmos mcp` is a zero-dependency MCP stdio server. Register it the same way you register any\nMCP server — `growmos integrate mcp` writes this for you, or paste it yourself:\n\n```json\n{\n \"mcpServers\": {\n \"growmos\": {\n \"command\": \"growmos\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n| Client | Where |\n|---|---|\n| Claude Code | `.mcp.json` in the repo (written by `growmos init` / `integrate claude`), or `claude mcp add growmos -- growmos mcp` |\n| Cursor | `.cursor/mcp.json` (written by `integrate cursor` / `integrate mcp`) |\n| Codex CLI | `~/.codex/config.toml`: `[mcp_servers.growmos]` `command = \"growmos\"` `args = [\"mcp\"]` |\n| Gemini CLI | `~/.gemini/settings.json` → `mcpServers.growmos` as above |\n| Grok CLI / others | their MCP config, same JSON |\n\n\n`mcp-name: com.codician/growmos`\n\nTools exposed: `growmos_context`, `growmos_query`, `growmos_entity`, `growmos_search`,\n`growmos_remember`, `growmos_link`, `growmos_journal`, `growmos_check`, `growmos_next`,\n`growmos_apply`, `growmos_status`, `growmos_sample`. Once registered, the agent calls them\ndirectly instead of shelling out — e.g. *\"what depends on the Store?\"* → `growmos_query`; *\"remember\nthat Scheduler now uses Kafka\"* → `growmos_remember` + `growmos_link`; *\"grow the graph\"* →\n`growmos_next` / `growmos_apply` in a loop.\n\n## What lives in `.growmos/` (commit it)\n\n```\n.growmos/\n config.json include globs, caps (max_docs_per_run, max_entities_per_doc), provider\n schema.json versioned entity types + predicate hints (bump on change; rows carry schema_version)\n state.json the loop's state file: runs, pending re-summarizations, last sample/eval\n sources.jsonl every document eaten: ref, sha256, status (pending|extracted|note|missing)\n mentions.jsonl raw per-document extraction output (append-only provenance)\n entities.jsonl canonical nodes (id, name, type, description, sources, mentions, provisional)\n aliases.jsonl alias → entity (the alias map)\n relations.jsonl edges: source, predicate, target, sources[], confidence (= corroborating docs)\n profiles/*.json hub-node profiles (summary, key facts, time range), keyed to source-set hash\n prompts/*.md the four playbook prompts + evaluator prompt — yours to tune\n eval/gold/*.json hand-labelled gold sets · eval/aliases.json scorer alias map\n journal.md the shared memo, append-only\n```\n\nPlain JSONL: diff-able, merge-friendly, greppable, viewable (`growmos view`) and exportable\n(`growmos export --format html|json|dot|mermaid|cypher|sql`). Storage is an infrastructure decision, not a pipeline decision:\nthe same schema maps onto Neo4j or three Postgres tables.\n\n## Configuration & big projects\n\nEverything tunable lives in `.growmos/config.json` (`growmos config [value]`). Defaults are\nsized for a normal repo; for a big one, three knobs matter:\n\n- **`max_docs_per_run`** (default 50/day) — a speed bump against runaway *unattended* runs, not a\n wall. When you or your agent are driving a backfill: `growmos next --force` or\n `growmos config max_docs_per_run 0`. Agents are told this, so they won't stall on it.\n- **`include` / `exclude`** — which docs are knowledge (READMEs, ADRs, design docs by default;\n never source code — agents write what code *means* via `remember`/`link`).\n- **`chunk_chars`** (6 000) — packet size for long documents.\n\nFull reference (all keys, monorepos, cost notes): [docs/configuration.md](docs/configuration.md).\n\n## Presets\n\n`growmos init --preset software|general|research|business` — same prompts, extended entity\nvocabulary (the playbook's five base types + domain types). `growmos remember --type NEWTYPE`\nextends the schema on the fly (schema version bumps).\n\n## Headless / overnight mode (optional)\n\n```bash\nexport ANTHROPIC_API_KEY=… # or OPENAI_API_KEY / XAI_API_KEY, or GROWMOS_PROVIDER + GROWMOS_BASE_URL\ngrowmos ingest --scan # extraction (fast model) → resolution → profiles (reasoning model)\ngrowmos query \"…\" --auto\n```\n\nFollows the playbook's model split (a fast model for high-volume extraction, a stronger model\nfor 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\nnext optimizations for large corpora.\n\n## Operational discipline (baked in)\n\n- **Sample the graph** — `growmos sample` (doctor warns after 7 days).\n- **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`.\n- **Version the schema** — `growmos schema bump --note … --add-type …`.\n- **Never lose a name** — unmatched names get single-element clusters.\n- **Every edge has provenance** — and a corroboration count.\n- **Re-summarize only when the source set changes** — profiles carry a source-set hash.\n- **Watch connectivity & density** — `growmos status` prints components / density / compression.\n\n## Docs\n\n- [METHODOLOGY.md](METHODOLOGY.md) — the living-knowledge-graph methodology, tool-agnostic\n- [docs/agents.md](docs/agents.md) — per-CLI setup and the agent protocol\n- [docs/file-format.md](docs/file-format.md) — store layout & JSON shapes\n- [docs/evaluation.md](docs/evaluation.md) — gold sets, scoring, prompt tuning loop\n- [docs/configuration.md](docs/configuration.md) — every config key, big projects, monorepos\n- [docs/headless.md](docs/headless.md) — provider mode, cron, CI\n- [examples/apollo](examples/apollo) — the playbook's Apollo corpus rebuilt in one script\n\n## Contributing\n\nPRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Run `python -m unittest discover -s tests`.\n\nMIT © 2026 [Codician](https://codician.com). Not affiliated with Anthropic; the methodology it\nimplements is a synthesis of Anthropic's public knowledge-graph cookbook and agent-pattern writing.\n", "bytes": 14587, "sha": "2a258f0c3a5db82e5560628489c6843fdc0230885386c2f82d0ed70ca6e9e630", "repo_slug": "codician-team/growmos", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_codician_growmos_aabfeea7/readme" }