# Sidegraph

> Durable decisions and non-derivable facts for coding agents, stored as repo-committed
> JSON records with a derived local index. Sidegraph reads Graphify's code/doc graph and
> delivers mistakes-first, task-scoped memory through MCP and Claude Code/Codex hooks.

Use [README.md](README.md) for task-oriented navigation. This index points to the guides
and exact contracts; it does not replace their version-specific requirements.

## Getting started

- [getting-started/installation.md](getting-started/installation.md) — installing Sidegraph and its Graphify dependency
- [getting-started/quickstart.md](getting-started/quickstart.md) — one end-to-end path: graph, store, host plugin, anchored gotcha, retrieval, commit
- [getting-started/bootstrap.md](getting-started/bootstrap.md) — preview, review, import, and prove retrieval from supported ADR/spec documents; host support and recovery
- [getting-started/claude-code-setup.md](getting-started/claude-code-setup.md) — wiring the MCP server and hooks into Claude Code
- [getting-started/codex-setup.md](getting-started/codex-setup.md) — wiring Sidegraph into Codex

## Concepts

- [concepts/decision-memory.md](concepts/decision-memory.md) — what a decision is, why mistakes rank first
- [concepts/mind-model.md](concepts/mind-model.md) — the mental-model idea: named Domains, TOC → drill_down → leaves, domain lifecycle
- [concepts/data-model.md](concepts/data-model.md) — Entity, Decision, Fact, AnchorBinding, Domain, Initiative
- [concepts/anchoring.md](concepts/anchoring.md) — tiered anchors, multi-anchor binding, domain-aware Tier-1
- [concepts/retrieval.md](concepts/retrieval.md) — the multi-altitude, budget-bounded read path (TOC, drill_down, thin tools)

## Integrations

- [integrations/graphify.md](integrations/graphify.md) — the engine seam: GraphifyReader over graph.json
- [integrations/claude-code.md](integrations/claude-code.md) — the host seam: MCP server + SessionStart/Stop/PreToolUse/SubagentStart hooks
- [integrations/codex.md](integrations/codex.md) — Codex integration

- [integrations/muse.md](integrations/muse.md) — experimental MCP/skills-only Muse installation and process-directory limits
- [integrations/opencode.md](integrations/opencode.md) — OpenCode V2 MCP and shared skills; native Git install/update guide

## Guides

- [guides/migrating-to-0.14.md](guides/migrating-to-0.14.md) — coordinated client upgrade, domain snapshot, Graphify upgrade, verification and rollback
- [guides/capturing-decisions.md](guides/capturing-decisions.md) — human-requested capture, agent proposals, ratification policies, and attached or standalone facts
- [guides/naming-your-domains.md](guides/naming-your-domains.md) — conversational and CLI paths for naming domains; membership guardrails and recovery
- [guides/retrieval-in-sessions.md](guides/retrieval-in-sessions.md) — reading SessionStart and task-context output, evidence, and unratified proposals
- [guides/surviving-refactors.md](guides/surviving-refactors.md) — rebuilding the graph, syncing anchors, healing stale decisions
- [guides/troubleshooting.md](guides/troubleshooting.md) — session integrity checks, notices, diagnostic commands, and fixes
- [guides/team-workflow.md](guides/team-workflow.md) — committing the store, PR review, merge conflicts, compaction, and onboarding
- [guides/semantic-docs.md](guides/semantic-docs.md) — the two-pass (AST + LLM) workflow over docs, concept/rationale anchoring, and the sidegraph-import bootstrap walkthrough
- [guides/verifying-your-setup.md](guides/verifying-your-setup.md) — a four-case post-install checklist: host wiring, durable capture/retrieval, ratification with evidence, and sync/repository hygiene
- [guides/ci-cd-maintenance.md](guides/ci-cd-maintenance.md) — GitHub Actions recipes for anchor health, store lint, and scheduled triage; CI proposes and opens PRs without ratifying

## Reference

- [reference/mcp-tools.md](reference/mcp-tools.md) — MCP tool parameters, return shapes, write guards, and retrieval behavior
- [reference/cli.md](reference/cli.md) — command flags, output, exit codes, import profiles, verification, and local diagnostics
- [reference/hooks.md](reference/hooks.md) — sidegraph-session-start, sidegraph-stop, sidegraph-pre-tool-use, and sidegraph-subagent-start: env, JSON I/O, guarantees
- [reference/git-bindings.md](reference/git-bindings.md) — commit trailers (candidate rules, comment-char handling, fail-open bounded stages, installation) and sidegraph-blame (trailer + provenance joins and output caps)
- [reference/configuration.md](reference/configuration.md) — environment variables, store/graph paths, retrieval budgets, and sync caches
- [reference/stability.md](reference/stability.md) — committed and provisional surfaces, compatibility policy, and behavioral guarantees
- [reference/operations.md](reference/operations.md) — what runs when, local writes and measured costs, the graph boundary, CI wiring, and unmeasured scale questions
- [reference/store-format.md](reference/store-format.md) — canonical JSON layout, derived state, migrations, archives, append-only writes, and merges
- [reference/releasing.md](reference/releasing.md) — maintainer release preparation, public snapshots, tagging, publishing, and post-release checks

## Pilot kit

- [pilot-kit/README.md](pilot-kit/README.md) — running the whitepaper's adoption gates on your own repository at team scale: corpus-fit pre-flight with a kill rule, store-blind question authoring, shadow-capture measurement, the paired battery, and default stop conditions
- [pilot-kit/questions-prompt.md](pilot-kit/questions-prompt.md) — the store-blind question-authoring prompt
- [pilot-kit/rubric-template.md](pilot-kit/rubric-template.md) — rubric conventions (checkable, specific, frozen)
- [pilot-kit/judge-prompt.md](pilot-kit/judge-prompt.md) — the blinded judging prompt
- [pilot-kit/corpus_fit.py](pilot-kit/corpus_fit.py) — the pre-flight script itself

## Engineering whitepaper

- [published whitepaper](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/whitepaper/index.md) — optional evidence and limits, including the corpus where memory cost +25.5% and answered worse; repository fit and staged adoption gates
