Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

21 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Context Layer

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.

What it provides

  • 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.

How memory flows

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.

Get started

Install Context Layer

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.py

On macOS and Linux:

python3 bootstrap.py

The 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.

Enable it in a project

Open a terminal in the project where you want agent context and run:

context-layer init

This 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.

Documentation

Architecture at a glance

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.

Code graph

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.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages