simplegraph-agentic

A lightweight persistent memory graph for AI coding assistants.

Your agent accumulates structured knowledge about your codebase — recurring bugs, deliberate decisions, dangerous code areas — and carries it across sessions without bloating every context window. Works with Claude Code, Cursor, GitHub Copilot, Antigravity, Zed, Codex CLI, and any tool that accepts custom instructions.

The Problem

Every AI coding session starts cold. The agent re-introduces the bug you fixed three times, undoes the architectural decision that was intentional, and generates the pattern your team banned. You re-explain the same context over and over — or worse, you don't, and it silently breaks things.

How It Works

Tiered loading — 29× fewer tokens at session start

Measured on a production codebase with 31 graph files:

42× reduction at session start. 6× reduction for a typical task. The savings compound across every request in a session — the agent reads ~944 tokens once, then loads only the 2–3 files relevant to the current task. Run bash scripts/token_benchmark.sh on your own graph to measure your numbers.

Typed nodes and edges — follow risk chains

Nodes have types (Component, Invariant, Regression, Decision, Watchlist) and typed edges. An agent can follow:

AUTH_SERVICE --VIOLATED_BY--> REG_TOKEN_LEAK (×3) --FIXED_BY--> DEC_ROTATE_ON_REFRESH

That chain tells the agent exactly what to be careful about and why — in 3 hops.

Priority — load critical context first

Compared to alternatives

Quickstart

git clone https://github.com/karstom/simplegraph-agentic.git
bash simplegraph-agentic/setup.sh /path/to/your/project

The installer copies core/ into your project, installs the right adapter for your AI tool, and prints next steps including the seed prompt.

Already installed? Re-run setup.sh on an existing project — it detects the existing graph and prompts you to upgrade in place (scripts and adapters refreshed, graph data untouched) or do a clean reinstall.

Manual install

1. Copy core/ into your project root.
2. Pick an adapter from adapters/ — see the Adapter Matrix below.
3. Bootstrap the graph: run sg seed (below) or scripts/seed_prompt.md in your AI tool.
4. Commit core/.

sg seed — bootstrap the graph from your repo's history

A new graph doesn't have to start empty. Everything it wants to store is already
latent in your repository: reverted and repeatedly-fixed files are regressions,
merge bodies and ADRs are decisions, emphatic comments and rule-shaped test names
are invariants, TODO/FIXME markers and high-churn files are watchlists, and your
directory structure is the component map. sg seed mines all of it —
deterministically, offline, no API key — into a draft you review before
anything is written.

cd mcp && npm install && npm run build && npm link   # installs the `sg` bin
cd /path/to/your/project
sg seed --dry-run     # mine and summarize, write nothing
sg seed               # mine, review the summary, confirm the merge

sg seed [PATH]
  --dry-run              mine and summarize, write nothing
  --since <ref|date>     history window (default: last 500 commits)
  --min-confidence <n>   drop draft nodes below threshold (default 0.5)
  --types <list>         restrict to given node types
  --max-per-type <n>     cap per type (default 15)
  --output <path>        write the draft bundle here
  --yes                  skip the interactive confirm

Every seeded node carries provenance (the commits and file locations it was
mined from) plus a confidence score, so you can audit — and delete — anything
that reads as noise. Re-running is safe: output is idempotent at the same
commit, re-runs after new commits add only what's new, and a seeded node you've
hand-edited is never overwritten (the conflict is reported instead). See the
"Seeded nodes" section of core/HOW_TO_UPDATE.md.

scripts/seed_prompt.md remains the LLM-assisted alternative: richer summaries,
but non-deterministic and model-dependent. sg seed is the reproducible baseline.

MCP Server (recommended for Claude Code)

The mcp/ directory exposes the graph as callable tools via the Model Context Protocol. This is more reliable than context injection alone — the agent actively calls tools rather than hoping it read a file at session start.

simplegraph_index              — Routing table (call at session start)
simplegraph_check_files        — Check files for known issues BEFORE editing
simplegraph_anti_patterns      — Anti-patterns list BEFORE generating code
simplegraph_nodes              — All nodes in a category
simplegraph_search             — Keyword search across all nodes
simplegraph_get_node           — Fetch a single node by exact ID
simplegraph_add_node           — Add a node after a bug fix or decision
simplegraph_update_index       — Add a new node to graph_index.md
simplegraph_update_node        — Update a field; increment REGRESSED_N_TIMES
simplegraph_archive_regression — Move a resolved regression to archive
simplegraph_scratchpad         — Session notes not yet ready to commit as nodes

See mcp/README.md for installation (Claude Desktop, Cursor, VS Code, .claude/settings.json). The setup.sh Claude Code path can generate .claude/settings.json automatically.

Best practice: use both — the adapter gives a session-start summary via context injection; the MCP server handles mid-task safety checks and structured updates.

Adapter Matrix

The generic adapter works with ChatGPT Projects, Gemini Gems, Windsurf, Aider, Cline, or any tool that accepts a persistent system prompt.

Zed note: The rules adapter covers Zed's native AI assistant panel. If you're using Claude Code in Zed's terminal or the claude-acp external agent, use the Claude Code adapter instead — those paths already read CLAUDE.md. See mcp/README.md for the Zed context server (MCP) configuration.

Graph Structure

core/
├── graph_index.md        # Mandatory session-start read (~50 lines)
├── anti_patterns.md      # What the AI should NEVER generate
├── invariants.md         # Hard rules ("never call X without Y")
├── regressions.md        # Bugs + REGRESSED_N_TIMES counters
├── decisions.md          # Architectural choices with rationale
├── watchlists.md         # Dangerous code areas + open issues
├── HOW_TO_UPDATE.md      # When and how to update the graph
├── components/           # One file per major service/module
├── archive/
│   └── resolved_regressions.md
├── auto_map.md           # (generated, gitignored) structural repo map
└── .scratchpad.md        # (gitignored) session-local AI notes

For multi-repo teams, a shared/ directory adds cross-repo invariants, decisions, and an org-level index. See shared/graph_index.md.

Edge types

Keeping the Graph Fresh

The graph only stays useful if it's updated when code changes.

CI check — add as a required branch protection rule so broken edges can never merge:

# .github/workflows/graph-check.yml
on: [pull_request]
jobs:
  graph-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: bash core/scripts/consistency_check.sh

Node updates grow naturally: fix a bug → add a Regression node in the same commit. Notice a bug recurs → call simplegraph_update_node to increment REGRESSED_N_TIMES. The graph improves through real usage — low quality at seed time is fine.

Multi-agent development

When several agents write the graph at once — parallel Claude Code sessions, worktree-based subagents, or a whole team — two failure modes appear that a single-agent setup never hits: concurrent writers racing on the same checkout, and parallel branches diverging before they merge. The MCP server and tooling handle both:

Propagation is not instant: an agent's node reaches others only when its branch merges, so commit graph updates in the same commit as the code and land them promptly. Because a graph node is agent-authored text that other agents later load as guidance, keep it in the PR diff where a human reviews it — the same trust boundary a shared shared/ graph relies on. See mcp/README.md for the full mechanism.

Scaling

Design Principles

1. Zero infrastructure. No databases, no servers. Plain markdown + git.
2. Stay small. 5 high-signal nodes beat 50 shallow ones.
3. AI writes the graph alongside the code. Graph updates go in the same commit as the fix.
4. Tiered loading. The agent reads ~50 lines at session start, not 5,000.
5. Git-native. Committed, versioned, branched, and reviewed like code.

Scripts

Contributing

See CONTRIBUTING.md.

License

MIT