Sidegraph

Sidegraph is a local MCP server and CLI for preserving engineering decisions and facts alongside your code. It records why a design was chosen, which alternatives were rejected, and what was learned during implementation, then retrieves that context for the files and symbols an agent is working on.

Records live in your repository as reviewable JSON files. A derived SQLite index supports retrieval; Graphify supplies the code and document graph used to anchor records. Claude Code and Codex plugins connect capture and retrieval to coding sessions.

• Keep decisions, rejected alternatives, and evidence with their provenance and history.
• Hand the agent the relevant mistakes and constraints before it edits, sized to fit its context.
• Review agent proposals before accepting them, or let low-risk ones be accepted automatically.
• Follow code through refactors, and flag records whose code changed or disappeared.

Documentation · Installation · Changelog · Contributing

Quickstart

Set up a repository (once)

You need Git, Claude Code or Codex, and uv, which also downloads Python 3.13 if you do not have it. On Windows you also need Git for Windows with its default options (details); run the commands below in PowerShell, using the Windows line where one is given. No API keys and no existing ADRs are required.

curl -LsSf https://astral.sh/uv/install.sh | sh                                     # uv on macOS, Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # uv on Windows

1. Build the code graph. Graphify maps your functions, classes and files, so a record can point at the exact function it is about.

uv tool install "graphifyy==0.9.6"   # two y's in the package name; the command is graphify
cd /path/to/your/repo
graphify update .
echo "graphify-out/" >> .gitignore   # the graph is rebuilt from your code; keep it out of git
Add-Content .gitignore "graphify-out/"   # the same line on Windows (PowerShell); do not use >> there

2. Create the store, the .sidegraph/ directory that holds the records:

uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init

It asks two questions. Both default to yes, so press Enter twice.

• Keep the code graph fresh? Yes installs a git hook that rebuilds the graph after each commit.
• Auto-ratify low-risk records? Yes means the lessons, gotchas and facts the agent proposes are accepted without review. Other proposals still wait for you. The answer is saved in .claude/settings.json, which you commit. The plugin applies it in Claude Code and in Codex, so it covers the whole team.

Details: sidegraph-init.

3. Install the plugin. It gives the agent the memory at session start and asks it to save new decisions at the end of a session. It updates itself: each new session downloads and runs the latest Sidegraph release.

In Claude Code, run these inside a session in the repository, then start a new session:

/plugin marketplace add SantyagoSeaman/sidegraph
/plugin install sidegraph@sidegraph

In Codex, run these in a terminal in the repository, then start codex and approve the Sidegraph hooks when it asks:

codex plugin marketplace add SantyagoSeaman/sidegraph
codex plugin add sidegraph@sidegraph

4. Record a decision. In a session, ask the agent, naming a real file and function:

Record this gotcha: the upstream API limits batch requests to 100 items. We rejected a single unbounded request because it fails for larger imports. Anchor it to import_batch in src/importer.py.

It is saved right away. Records the agent proposes on its own may wait for your review: run /sidegraph:ratify-decisions in Claude Code, or ask Codex to "review pending decisions".

5. Check and commit. Start a new session and ask: "Before I edit src/importer.py, what should I know?" The agent should show the gotcha. Then commit .sidegraph/ and .gitignore, and .claude/settings.json if step 2 created or changed it. The index file inside .sidegraph/ is git-ignored automatically.

Each teammate

After cloning, each teammate runs steps 1, 2 and 3. In a clone, step 2 leaves the committed records and settings alone. It only installs the graph hook there.

Next, name your domains to give the memory a table of contents, or import existing ADRs and design specs with the preview-first bootstrap. The verification checklist covers the whole workflow.

Other options

• Without the graph. Skip step 1 and answer no to the first question in step 2. Records then attach to whole files instead of functions.
• Versions. You always run the latest release. The plugin and the step 2 command install Sidegraph from the public repository on GitHub, whose main branch changes only when a release is published. To pin a version instead, see pinning.
• Sidegraph commands in your own terminal. Optional: uv tool install git+https://github.com/SantyagoSeaman/sidegraph.git@main, from the same place as the plugin. It does not update itself, so after each release run uv tool upgrade sidegraph (details).
• Other MCP clients. Run sidegraph-mcp over stdio; see the MCP reference and configuration. Automatic memory needs a host with hooks, such as Claude Code or Codex.
• Windows details, including what the plugins need from Git for Windows: Windows setup.

Why

Code describes the current implementation, but often omits the alternatives a team tried, operational constraints it discovered, and reasons for changing direction. Sidegraph captures that reasoning and links it to the code and planning documents it concerns. It works alongside an existing ADR or specification process.

The useful starting point is a project with decisions worth retaining and people willing to review them. Memory quality depends on capture, review, and whether the agent actually retrieves it. Small tasks answerable directly from code may gain little from the extra context. The engineering whitepaper describes the evidence, negative results, and adoption criteria; the pilot kit helps evaluate it on your own repository.

How it works

1. Capture. During a session the agent saves a decision when you ask for one. At the end of a session the plugin reminds it to propose the decisions worth keeping. Secrets are redacted before anything is written.
2. Review. You accept or drop what the agent proposed; Sidegraph calls this ratifying. Records are JSON files in .sidegraph/, committed with your code.
3. Anchoring. Each record is linked to the functions, classes, files or document headings it is about, using the graph Graphify builds from your code. When a refactor moves code, Sidegraph follows the move; when it cannot tell where the code went, it flags the record for review.
4. Recall. At the start of the next session the agent gets a short table of contents of the project's areas, called domains. Before changing a file it asks for that file's records, with known mistakes first. In Claude Code, the agent also receives a file's records the first time it reads or edits that file.
5. Subagents. In Claude Code, when the agent hands a task to a subagent, the records for the files named in that task are added to it. In Claude Code and Codex, each new subagent is told that the memory exists and how to use it.

Domains are named by you or proposed by the agent; each one says what an area is for and which code belongs to it. See the mind model and the anchoring model.

What gets stored

Nothing is ever deleted. A reversed decision is closed and replaced by a new one, so "tried before, abandoned because…" stays retrievable with get_entity_history. Dropping a proposal marks it rejected; it stays in the history too.

Facts follow the same review and history rules as decisions. Accepting or dropping a decision also accepts or drops the pending facts attached to it. Details: docs/concepts/data-model.md and docs/guides/capturing-decisions.md#facts-the-evidence-layer.

MCP tools

The sidegraph-mcp stdio server exposes retrieval, capture, review and maintenance tools. The ones an agent uses most: get_task_context (the records for the files or functions it is working on), drill_down (everything in one domain), get_entity_history (every decision ever made about one function or file, including reversed ones), propose_decisions (drafts for review) and ratify (accept or drop drafts).

See the MCP reference for the complete tool set, schemas, return shapes, and side effects. The CLI reference covers setup, scripted use, and CI maintenance. Tool names and return shapes are provisional before 1.0.

Works on code and on docs

Anchor decisions to functions and classes, or to headings in your architecture documents; Graphify builds both graphs without an LLM. sidegraph-bootstrap turns existing ADRs and design specs into anchored decisions, also without an LLM.

An optional semantic pass (graphify extract, which needs an API key for its model provider and caches results per file) goes deeper on documentation: it turns prose into concepts and themes that records can anchor to. Walkthrough: docs/guides/semantic-docs.md.

Trust & privacy

• Local runtime: Sidegraph reads repository files and the graph, and writes records, a derived index, and optional setup or export files. It makes no network calls of its own and sends nothing anywhere. Installing and updating it downloads it from GitHub. What the agent does with Sidegraph's answers is up to your agent host, which sends them to its model provider like any other context. Graphify's optional semantic pass uses its own model provider. See SECURITY.md for the data boundary.
• Reviewable capture: text is redacted before storage using best-effort patterns. Review drafts and scan the committed store for secrets. Agent proposals wait for human review unless the project answered yes to auto-ratify in sidegraph-init; even then, architecture decisions and domains wait. See the ratification policy.
• Preserved history: a reversal closes the old record and adds a new one. Only two things change a record in place: review sets its status, and a confirmed file move updates where its anchor points.
• Local counts: for sidegraph-stats, Sidegraph counts how often memory was shown. The counts stay in .sidegraph/index.db, which is git-ignored and never leaves your machine. To stop counting, set SIDEGRAPH_TELEMETRY=off.

The engine underneath

The graph of your code and documents comes from Graphify, built without an LLM. Sidegraph only reads it and never writes into it. Without a graph, records anchor to files and domains, and recall still works. Three things need the graph: anchoring a record to a function, grouping related code automatically, and following moved code (see the operations reference). The graph and the local index can be rebuilt at any time. The JSON records in .sidegraph/ cannot: they are the source of truth, so keep them in your repository and backups.

Status

Sidegraph is in beta. Read the stability policy before building automation against it. By default the plugin follows the latest release; for reproducible deployments, pin a version. The changelog records release changes.

The platform badges at the top summarize the 0.13.0 release checks of 2026-10-14: Windows x64 and macOS arm64 both ran the full plugin session for Claude Code and Codex. The badges are not live CI status; see Platform coverage.

Contributing and support

Bug reports, questions, and feature requests are welcome in GitHub Issues. Include the commands you ran, expected and actual behavior, and package versions; remove secrets from logs. For patches, see Contributing and the Code of Conduct. Report vulnerabilities through the private channel in SECURITY.md.

The public repository holds the released code; development happens in a private repository. Contributions are reviewed here and carried over, with attribution, before the next release.

Documentation

Getting started · Concepts · Guides · Reference · Integrations (Graphify · Claude Code · Codex) · Verify your setup · Operations · Pilot kit · Engineering whitepaper

License

Apache-2.0.