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. OpenCode V2 and the experimental Muse and Grok Build expose MCP tools and shared skills for explicit retrieval and capture.

• 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, one of the hosts below, 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 block where one is given. No API keys and no existing ADRs are required.

macOS, Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux follows the macOS commands but is not among the checked platforms. Open a new terminal afterwards so uv is on your PATH, then change into the root of your repository (cd /path/to/your/repo). Every command below runs there, except the Muse install, which says otherwise.

Already using Sidegraph? (New here? Skip to step 1.) Follow the 0.14 migration guide before upgrading Graphify, so accepted domains keep their membership. Update every client first, then use the existing-install recipe for your host below. Claude Code and Codex keep the same sidegraph@sidegraph identity; no uninstall/reinstall is needed.

The short path (macOS or Linux, Claude Code; every step is explained below):

uv tool install "graphifyy==0.9.90" && GRAPHIFY_NO_AUTO_REFRESH=1 graphify update .   # step 1 (optional)
uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init   # step 2: press Enter twice

then, in Claude Code, /plugin marketplace add SantyagoSeaman/sidegraph and /plugin install sidegraph@sidegraph (step 3), and ask the agent to record a gotcha (step 4).

1. Build the code graph (recommended; you can skip it, and then answer no to the first question in step 2). Graphify maps your functions, classes and files, so a record can point at the exact function it is about.

macOS, Linux:

uv tool install "graphifyy==0.9.90"   # two y's in the package name; the command is graphify
export GRAPHIFY_NO_AUTO_REFRESH=1     # stops Graphify rewriting its skill files in your agent after an upgrade (this shell only; the git hook in step 2 sets it itself)
graphify update .                     # ends with "Code graph updated."
grep -qxF "graphify-out/" .gitignore 2>/dev/null || printf '\ngraphify-out/\n' >> .gitignore   # the graph is rebuilt from your code; keep it out of git

Windows (PowerShell):

uv tool install "graphifyy==0.9.90"   # two y's in the package name; the command is graphify
$env:GRAPHIFY_NO_AUTO_REFRESH = "1"   # stops Graphify rewriting its skill files in your agent after an upgrade (this window only; the git hook in step 2 sets it itself)
graphify update .
if (-not (Select-String -Path .gitignore -Pattern "^graphify-out/$" -Quiet -ErrorAction SilentlyContinue)) { Add-Content .gitignore "`ngraphify-out/" }   # keep the graph out of git; do not use >> in PowerShell

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

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

The command is the same on Windows. It prints created store: .sidegraph and asks two questions. Both default to yes, so press Enter twice. Outside a terminal (a script, CI, an agent session) it asks nothing, installs no git hook and leaves .claude/settings.json alone; pass --hooks and --ratify-policy auto-low-risk to answer yes up front.

• Keep the code graph fresh? Yes installs a git hook that rebuilds the graph after each commit.
• Auto-ratify low-risk records? Yes (the default) means the lessons, gotchas and facts the agent proposes are accepted without review once they are anchored to code; answer no to review every proposal. ADRs, constraints and domains always wait for you. The answer is saved in .claude/settings.json, which you commit. Sidegraph reads it for every MCP integration unless an explicit SIDEGRAPH_RATIFY_POLICY overrides it, so teammates use the same project policy.

Details: sidegraph-init.

3. Choose one host. Install its plugin, then start a new session in this repository.

Claude Code is shown first; open the section for another host. Host plugin updates and the MCP runtime are separate: the default runtime follows the public repository's main, which advances at releases; that does not refresh cached skills, manifests or hook definitions. Use your host's update recipe after a release.

Claude Code

In a Claude Code session in the repository:

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

Review the installation summary and any approval prompts, then start a new Claude Code session. The plugin provides MCP, skills, session memory, capture reminders and context on reads. To check the connection, run /mcp in the new session: sidegraph should be listed as connected. For an existing install, run these in your terminal:

claude plugin marketplace update sidegraph
claude plugin update sidegraph@sidegraph

Keep the same install scope; see the Claude Code guide. Start a new session after updating, or use /reload-plugins and review its prompts.

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

codex plugin marketplace upgrade sidegraph

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

grok plugin marketplace update
grok plugin update sidegraph

git clone -c core.autocrlf=false https://github.com/SantyagoSeaman/sidegraph.git sidegraph-plugin
muse plugins install ./sidegraph-plugin/plugin/sidegraph
muse plugins inspect sidegraph

muse plugins approve sidegraph

git -C sidegraph-plugin pull --ff-only
muse plugins update sidegraph
muse plugins inspect sidegraph

muse plugins approve sidegraph

opencode plugin add 'git+https://github.com/SantyagoSeaman/sidegraph.git#main'

opencode plugin check 'git+https://github.com/SantyagoSeaman/sidegraph.git#main'
opencode plugin update 'git+https://github.com/SantyagoSeaman/sidegraph.git#main'

First memory

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.

A record you ask for is accepted at once when the agent saves it directly (add_decision), or when auto-ratify is on (step 2) and the function is found in the graph; otherwise it waits for your review, like the records the agent proposes on its own. Ask the agent to review pending Sidegraph decisions through MCP on any host; Claude Code also offers /sidegraph:ratify-decisions.

5. Check and commit. Start a new session and ask: "Before I edit src/importer.py, what should I know? Retrieve Sidegraph context for that file with get_task_context." A record still waiting for review is shown tagged [unratified]. The reply should contain the gotcha and the rejected alternative, for example "import_batch calls an upstream API that accepts at most 100 items per batch request". The agent should show the gotcha on every host, including those without lifecycle hooks. 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.

If something does not work

• Run sidegraph-doctor (as uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-doctor, or by its plain name if you installed the CLI, see Other options): it lists what is wrong with the store, the graph and the wiring. Troubleshooting explains each message, and the verification checklist walks the whole workflow.
• get_task_context finds nothing for a function: there is no graph yet (step 1), or the record was saved before the graph existed; run sidegraph-sync.
• The agent has no Sidegraph tools: start a new session after installing, approve the plugin's prompts (Codex: its hooks too), and in Claude Code check /mcp.

Removing Sidegraph. Remove the plugin with your host's plugin command (/plugin uninstall sidegraph@sidegraph in Claude Code, grok plugin uninstall sidegraph in Grok Build). sidegraph-init --remove-hooks removes the git hook. The records in .sidegraph/ are your project's memory and are committed: delete them only if you mean to lose them. graphify-out/ can always be deleted and rebuilt.

Other options

• Without the graph. Skip the Graphify install and graphify update in step 1 (still work from the repository root) and answer no to the first question in step 2. Records then attach to whole files instead of functions.
• Versions. The default MCP runtime 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. 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 Claude Code or Codex session the plugin reminds it to propose decisions worth keeping. In OpenCode, Muse and Grok Build, ask for capture explicitly. Known secret patterns are redacted before storage (best effort).
2. Review. You accept or drop what the agent proposed; Sidegraph calls this ratifying. Records are JSON in .sidegraph/, committed with your code: one file per record, or lines in shard files once maintenance has packed them.
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. Claude Code and Codex inject a short table of contents of the project's areas, called domains, at session start. In every host, ask the agent to retrieve a file's records with get_task_context before changing it, 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 a decision also accepts the pending facts attached to it; dropping it drops them unless they still back another live decision. 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 (the default answer; SIDEGRAPH_RATIFY_POLICY overrides it); even then, architecture decisions, constraints and domains wait. See the ratification policy.
• Preserved history: a reversal closes the old record and adds a new one. Records change in place only in narrow ways: review sets a status, closing a superseded record sets its end date and status, adding anchors adds bindings, and a confirmed file move updates where an 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/ (files or shard lines) 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. For reproducible deployments, pin a version. The changelog records release changes.

The platform badges cover full Claude Code and Codex plugin sessions on Windows x64 and macOS arm64, with Python 3.13 and 3.14, including Windows PowerShell 5.1 without PowerShell 7. Muse, OpenCode V2 and Grok Build are checked on macOS only. See Platform coverage for limits.

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 · ADR export · Reference · Integrations: Graphify · Claude Code · Codex · Muse · OpenCode V2 · Grok Build · Verify your setup · Operations · Pilot kit · Engineering whitepaper

License

Apache-2.0.