Persistent, model-agnostic project memory for AI coding agents. Context Layer stores project handoffs, decisions, and dead ends in SurrealDB and exposes them through the Model Context Protocol (MCP), so a new session on any supported agent can pick up where the last one stopped, without relitigating settled choices or retrying what already failed.
Project status: The default deployment is local-first and intended for development. It is not a hardened multi-user hosted service. See Operating Context Layer before exposing any service or storing sensitive data.
- Handoffs: structured checkpoints with a summary, decisions, next steps, branch, content, and file and issue references.
- Decision ledger: settled decisions and dead ends per project, kept across handoffs, with supersession when a decision changes.
- Search: full-text, vector, and hybrid search over saved handoffs, with embeddings computed locally.
- Bounded context: token-budgeted context assembly, and portable Markdown capsules for chats without MCP.
- Automatic capture: lifecycle adapters that load context and save checkpoints for supported clients.
- Notes at edit time: in Claude Code, ledger entries about a file appear right before the agent edits it.
- 19 MCP tools, a project context resource, an optional HTTP API for non-MCP agents, and command-line utilities for export/import, consolidation, backup, correction, and lifecycle checks.
Context Layer stores and retrieves context that is explicitly given to it. It does not synchronize complete private conversation histories across platforms. Automatic capture depends on a supported client adapter; otherwise, an agent must call the MCP tools.
| Moment | What happens |
|---|---|
| Session start | The latest handoff and the decision ledger are injected, within a token budget. |
| While working | The agent records decisions and dead ends with record_decision. |
| Before an edit | Ledger entries naming the file appear next to the edit (Claude Code). |
| Compaction | The transcript is saved first; afterwards Claude Code's own summary is stored as a distilled handoff, and its "Errors and fixes" become dead ends. |
| Session end | The transcript is saved as a handoff, and CONTEXT.md is written to the project. |
Support differs by client:
| Client | Loads at start | Saves automatically | Compaction summary | Edit notes |
|---|---|---|---|---|
| Claude Code | Yes | Yes | Yes | Yes |
| Codex | Yes | Yes | No | No |
| GitHub Copilot | Yes | Yes, past a token threshold | No | No |
| OpenCode / OpenWork | No | Yes, with the plugin | No | No |
| VS Code, Cursor, Claude Desktop | No | No | No | No |
Clients with a "No" still get every MCP tool; the agent has to call them. See MCP-only agent guidance.
Without ANTHROPIC_API_KEY, transcripts are summarized by local rules, which are rough. Claude Code's compaction summaries and anything recorded with record_decision don't depend on those rules.
Requirements: Python 3.12+, SurrealDB 3.x with the surreal executable on PATH, and network access for the initial package and model downloads. Node.js is needed for the Copilot and OpenCode hooks.
From this repository root, create .env from .env.example, set a local database password, then run the installer.
On Windows:
python bootstrap.pyOn macOS and Linux:
python3 bootstrap.pyThe installer creates venv, installs the package, registers the context-layer command, generates client configuration for this checkout, starts SurrealDB, applies migrations, and runs readiness checks. On Windows the command is added to the current user's PATH, so open a new terminal. On macOS and Linux it is linked into ~/.local/bin, and the installer tells you if that folder isn't on your PATH.
Open a terminal in the project where you want agent context and run:
context-layer initThis creates a stable project identity and configures the supported project-scoped MCP clients and hooks. Restart the client afterwards. To configure only selected clients, pass --client one or more times; for example, context-layer init --client codex --client opencode. Add --no-db to write configuration without starting SurrealDB. Claude Desktop is opt-in because its configuration is user-wide: context-layer init --client claude_desktop.
See Getting started for verification, upgrades, and troubleshooting.
- Getting started — install, initialize a project, connect clients, verify readiness, and upgrade.
- Configuration — environment variables, project identity, generated files, and client selection.
- Architecture — components, data model, context flow, and current limitations.
- MCP and HTTP reference — tools, resource, HTTP API, and client adapters.
- Operating Context Layer — services, Docker, backups, logs, data handling, and troubleshooting.
- Development — tests, repository workflow, and CI.
- Retrieval evaluation — compare search modes against labeled handoffs.
- Repository map — source tree and entry points.
- Migration workflow — how to evolve the SurrealDB schema.
- MCP-only agent guidance — instructions for clients without lifecycle hooks.
- Architecture diagram and quick reference — one-page Mermaid overview.
- Changelog — what changed.
AI agent / MCP client scripts and non-MCP agents
│ tools and resource (stdio) │ HTTP
▼ ▼
context_layer.server ── adapters ── scripts/api_server.py
│ and hooks │
▼ ▼
context_layer.core ── SurrealDB (handoffs, decision ledger)
└── FastEmbed (local embeddings)
The server exposes MCP; the core package stores and retrieves handoffs and decisions; adapters connect agent lifecycle events to checkpoint and resume behavior. See Architecture for details and scope.
graphify-out/ contains generated architecture graph data, a browser viewer, report, and supporting metadata. These checked-in artifacts can lag behind the source. Open graphify-out/graph.html or read graphify-out/GRAPH_REPORT.md; see Repository map for refresh and ignore details.