Sidegraph

Platform badges summarize the release checks of 0.12.0, verified on 2026-10-12; they are not live CI status. What each check covers is in Platform coverage.

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.
• Retrieve relevant mistakes and constraints before editing, within a character budget.
• Review agent proposals before accepting them; manual ratification is the default.
• Detect changed code and unresolved anchors for review after refactors.

Documentation · Installation · Changelog · Contributing

Quickstart

You need Python 3.13+, uv, and a repository to work in. See installation for platform limitations and manual MCP configuration. Existing ADRs and API keys are not required for the local workflow.

Windows: native x64 CI checks the portable core and installed-wheel MCP stdio on Python 3.13/3.14, and each release runs real Claude Code and Codex plugin sessions there (installation, capture and fresh-session recall). The supplied plugins require a POSIX shell for their MCP launchers and hooks, and Codex hooks need PowerShell 7. The manual recipes use Bash; run them inside WSL. See Windows setup and release caveats.

Start with the plugin: connect your agent using one of the host guides:

Then install the verified graph-engine version and initialize your repository. The commands run Sidegraph through uvx, the way the plugin does, so nothing else needs installing (@main is a mutable ref; to pin it see mutable development references):

uv tool install "graphifyy==0.9.6"  # Package name has two y's; the command is graphify.
cd /path/to/your/repo
graphify update .
uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init

(uv tool install sidegraph puts the bare sidegraph-* names on your PATH. It is optional beside a plugin and the usual setup without one. It never updates itself, so run uv tool install sidegraph@latest after every release; see installation.)

sidegraph-init creates .sidegraph/ and prints setup guidance. In an interactive terminal it also offers graph-refresh hooks and a ratification policy; review those choices before enabling them. Graphify's optional [mcp] extra installs its separate MCP server and is not needed by Sidegraph.

In a connected session, ask the agent to record a decision, for example:

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.

Replace the example with a finding and file from your project. Ask for the context for that file in a new session to verify retrieval. Commit the canonical .sidegraph/ files with the related code; its derived index is gitignored. The verification checklist covers the full workflow.

Next, name your domains to create a project table of contents. If you already have ADRs or design specs, use the preview-first bootstrap to import them.

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

 you work a session ──▶ Stop hook nudges the agent to distill durable decisions
                                │ propose_decisions / propose_domains (secrets redacted)
                                ▼
                        you ratify / drop  ──▶  append-only decision log,
                                                 committed with your repo
                                                        │
 next session ◀── SessionStart TOC            anchored to entities in the
 of named domains ◀── get_task_context ◀────── engine's graph (read-only);
 mistakes first        drill_down             re-anchored after refactors
 Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)

Subagents get the memory too: on Claude Code a hook appends the decisions for the files a subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new subagent that decision memory exists and how to ask it.

The graph describes code and document structure and can be rebuilt from source. The store preserves decisions independently of that graph. Anchors identify functions, classes, files, or document headings rather than line numbers; synchronization follows confirmed moves and reports ambiguous or missing matches for review.

Named domains group related records and code into a described table of contents. Their membership is based on durable anchors and path rules. See the mind model and anchoring model.

What gets stored

Append-only is a feature: a reversed decision is closed and superseded, never deleted — "tried before, abandoned because…" stays retrievable via get_entity_history.

Facts follow the same append-only and ratification rules as decisions; ratifying or dropping a decision carries its still-pending facts along in the same verdict. 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, ratification, and maintenance tools. Start with get_task_context for files and symbols, drill_down for a domain, and get_entity_history for a decision chain. propose_decisions creates reviewable drafts; ratify accepts or drops proposals.

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 markdown (LLM-free graph build, non-git folders supported). sidegraph-bootstrap parses existing ADRs and design specs into anchored decisions deterministically, no LLM.

An optional semantic pass (graphify extract, one API key, cached per file) goes a layer deeper on documentation: prose becomes concept nodes and thematic clusters, giving retrieval a richer graph to anchor against. 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 and sends no remote telemetry. Installation and updates download packages; your agent host controls where MCP results are sent. Optional Graphify semantic analysis uses its configured 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 ratification by default; automatic ratification is an explicit policy choice.
• Preserved history: reversals close a record and append a successor. Ratification updates status, and confirmed file moves may update anchor descriptors. Local usage diagnostics live in the gitignored index; SIDEGRAPH_TELEMETRY=off disables recording.

The engine underneath

Entity extraction and graph construction come from Graphify (its LLM-free build covers both code and markdown); Sidegraph never re-implements them or writes into the engine's output. The engine is optional at runtime: without a graph, records anchor to file paths and domains and retrieval still works, but symbol-level anchors, communities, and moved-code resolution need it (see the operations reference). Graph output and the local SQLite index are derived data. Canonical JSON records and archives in .sidegraph/ are the durable source of truth; include them in your repository and backup policy.

Status

Sidegraph is in beta. Read the stability policy before building automation against it, and pin a package version or commit for reproducible deployments. The changelog records release changes.

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 is a release snapshot. Contributions are reviewed there and ported to the development repository 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.