growmos/docs/agents.md

Using growmos with your agent CLI

growmos is agent-native: your CLI agent is the model. The CLI does the deterministic work and hands judgment work over as task packets. No API key is required.

The protocol every agent follows

1. Session start → growmos context (Claude Code does this automatically via a SessionStart hook).
2. Cross-cutting question → growmos query "<question>" and answer only from the triples, citing edge ids.
3. Learned/decided something durable → growmos remember / growmos link / growmos journal.
4. Grow the graph → growmos next → produce the JSON → run the printed growmos apply … → repeat.
5. Before asserting facts → growmos check "<claims>".
6. Session end → growmos journal "<summary>".

The block that teaches this to agents is written by growmos integrate <target> (or growmos init --agent …).

Claude Code

growmos init --agent claude     # or: growmos integrate claude

Writes:

• CLAUDE.md — protocol block (marker-delimited, idempotent)
• .claude/skills/growmos/SKILL.md — a skill that triggers on graph-related asks and explains the packet rules
• .claude/settings.json — hooks: SessionStart runs growmos context --brief (injected into context), Stop runs growmos scan --quiet (queues changed docs)
• .mcp.json — registers growmos mcp as an MCP server (tools: growmos_query, growmos_remember, …)

Try: "grow the knowledge graph until it's up to date" · "what does the graph say about the Store?" · "remember that the Scheduler now depends on Kafka".

Codex CLI

growmos init --agent codex      # writes the AGENTS.md block

Codex reads AGENTS.md. To use MCP tools instead of shelling out, add to ~/.codex/config.toml:

[mcp_servers.growmos]
command = "growmos"
args = ["mcp"]

Grok CLI and other CLIs

growmos init --agent grok       # AGENTS.md block + .mcp.json

Most CLIs honour AGENTS.md. If yours uses a different instructions file, append the block:

growmos integrate file --file .grok/GROK.md

If it supports MCP, point it at growmos mcp (stdio).

Cursor

growmos init --agent cursor     # .cursor/rules/growmos.mdc, alwaysApply: true

Gemini CLI

growmos init --agent gemini     # GEMINI.md block

MCP (any client)

growmos integrate mcp        # writes .mcp.json (and .cursor/mcp.json if .cursor/ exists)

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

Claude Code also accepts claude mcp add growmos -- growmos mcp. Codex: ~/.codex/config.toml ([mcp_servers.growmos] command = "growmos" args = ["mcp"]). Gemini: ~/.gemini/settings.json.

Everything at once

growmos init --agent all        # claude + codex + gemini + cursor + git hooks + CI workflow

Git hooks & CI

• growmos integrate hooks → post-commit, post-merge, post-checkout run growmos scan --quiet so edited docs are queued for the next session (safe no-op if growmos is absent; respects core.hooksPath).
• growmos integrate ci → .github/workflows/growmos.yml runs status, doctor, eval on PRs.

Multi-agent teams (orchestrator–workers)

The graph is the blackboard. Give each worker its slice of sources (growmos add … per worker, or separate include globs), let workers run next/apply in their own context windows, and let the resolver step (growmos resolve → apply) merge surface forms across workers ("Acme Corp", "ACME Corporation", "acme"). The synthesizer never re-reads the raw documents: it runs growmos query and cites edges. Everything writes to the same JSONL files; commit and merge like code.

Seeing the graph

growmos view writes .growmos/graph.html (self-contained, offline) and opens it: force layout sized by degree, colored by type, search, type filters, and a card per node with description, profile, edges (with edge ids, corroboration and provenance) and aliases. --focus <entity> opens on a node; --out path.html writes elsewhere (share it, embed it in CI artifacts).

Packet anatomy

=== growmos task packet: extraction · docs/adr-001.md · chunk 1/1 ===
Respond with JSON of this shape (strict: no extra keys):
{"entities": [...], "relations": [...]}
Write it to `.growmos/cache/extract_src_….json` (or pipe it on stdin), then run:
    growmos apply extraction .growmos/cache/extract_src_….json --source src_… --chunk 0
--- prompt ---
<the prompt from .growmos/prompts/extract.md, rendered>

growmos next --json gives the same as structured data (text, meta.apply, meta.out_file).