Deep Context

Local cognitive infrastructure for AI coding tools. Not a memory feature — the layer that gives the model the ability to learn from you, continuously, across every tool you use, with optional weight-level adaptation for local models.

Every coding assistant today is stateless at its core. The industry's response has been to make context windows bigger — two million tokens, five million tokens, eventually all your code and history stuffed into context. This is a treadmill, not a destination. The model itself is not getting smarter. It is being handed a fatter dossier each turn.

Deep Context is the alternative path. A local daemon that learns from you continuously, surfaces relevant knowledge before you know you need it, and — on local models — actually updates the model's weights so what it learned becomes part of how it thinks.

It's worth being precise, because there's a lot of "memory" branding floating around:

• This is not Claude Code's CLAUDE.md / Dream, which is a single-tool markdown store reread each turn. It works inside Claude Code only and stores raw text.
• This is not ChatGPT Memory, which is a vendor-locked, cloud-hosted notes file ChatGPT consults when it decides to.
• This is not Cursor Rules, which is a static config file the editor sends as system prompt.
• This is not RAG, which retrieves documents on demand when the model asks.

Those are memory features — places a single product stashes notes about you, then occasionally references. Deep Context is infrastructure. It sits underneath every coding tool you use and operates four distinct mechanisms simultaneously, only one of which any of the above does.

1. Cross-tool memory ledger. A single SQLite store, on your machine, shared by every AI coding tool you point at it. Claude Code's plugin, Cursor over the OpenAI proxy, a local Qwen — they all write to and read from the same ledger. A fact you taught Claude Code on Monday surfaces in Cursor on Tuesday and in a local model on Wednesday. No vendor lock-in, no per-product silos.

2. Sleep-time consolidation. A background worker (your choice of Anthropic Haiku, OpenAI gpt-4.1-mini, or a local Ollama model) reads completed turns and extracts durable facts — preferences, conventions, decisions, anti-patterns — distinct from transient chatter. Three-tier memory architecture (Priority / Working / Archival) with automatic promotion on reinforcement, demotion on disuse, contradiction tracking, and configurable forgetting. This is the part that's surface-similar to existing memory features but already deeper: it's distilling structured facts, not storing chat logs.

3. A learned surfacing brain (the Predictor). This is the structural step nothing else has. Most "memory" systems do one of two things at injection time: dump everything (and dilute attention), or ask the model to call a retrieval tool (and miss the cases where the model doesn't know it should ask). Deep Context runs a small purpose-built cross-encoder reranker (bge-reranker-v2-m3) that scores every memory against your live prompt and decides which to surface. It's trained continuously via DPO on whether you accepted, corrected, or ignored each surfacing — so it gets sharper at predicting which fact you'll need before you ask. The model never queries. The relevant memory is simply present in its context when it starts generating.

4. Parametric learning (local models only). This is the part no vendor memory feature does, and it's the difference between "an AI with a great filing cabinet" and "an AI that has internalized you." For users running a local model (Qwen, Llama, etc.), Deep Context can fine-tune the model itself on your accumulated preferences via LoRA with Orthogonal Subspace Fine-tuning to prevent catastrophic forgetting. Held-out MMLU / HumanEval evaluations gate every update; regressions roll back automatically. Over time, your facts stop needing to be surfaced into context — they're part of how the model thinks.

Local-model users also get mid-stream injection (pause generation, splice memory into the active context, resume — for when relevance shifts mid-response) and KV cache injection (memory pre-computed into the attention cache at consolidation time, spliced in at zero tokenization cost). Both are research-grade and feature-flagged.

RAG is the closest in spirit and worth contrasting in detail:

RAG is reactive. Deep Context is anticipatory. You can run both — they don't conflict. RAG is the right tool for "ground this in a 10,000-page PDF." Deep Context is the right tool for "remember how I work across every project, every tool, every day, and eventually adapt the model itself to me."

• Switch between Claude Code, Cursor, Codex CLI, Aider, and a local Qwen mid-task; each one picks up the others' context.
• Reject a pattern once. Never see it suggested again, by any tool.
• Migrate from NextAuth to Lucia. Watch every tool stop referencing NextAuth within a turn or two.
• Run a 7B local model on a year of your accumulated preferences. Watch it generate code that looks like you wrote it.
• All of the above without a byte of memory leaving your machine.

Requirements: macOS or Linux, uv, Python 3.11+.

git clone https://github.com/gostastv/deep-context
cd deep-context
uv sync --all-extras
uv run dc-daemon &           # start the daemon (port 7472)
uv run dc status              # confirm it's healthy

Open the read-only inspector to watch the system breathe:

open http://127.0.0.1:7472/inspect

Now wire up your tools.

Add the hooks to ~/.claude/settings.json (merge alongside any existing top-level keys):

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/session_start.py" }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/user_prompt_submit.py" }] }
    ],
    "PreToolUse": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/pre_tool_use.py" }] }
    ],
    "PostToolUse": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/post_tool_use.py" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/stop.py" }] }
    ],
    "SubagentStop": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/stop.py" }] }
    ],
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/pre_compact.py" }] }
    ],
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "/absolute/path/to/deep-context/packages/dc-claude-plugin/hooks/session_end.py" }] }
    ]
  }
}

Register the MCP server with the Claude Code CLI (it lives in ~/.claude.json, not settings.json):

claude mcp add deep-context-memory --scope user -- \
  python3 /absolute/path/to/deep-context/packages/dc-claude-plugin/mcp/server.py

Restart Claude Code. The hooks fire automatically on each turn; the MCP server adds four slash commands:

• /memory list — what's currently surfaced
• /memory pin "fact" — pin a fact to Priority tier
• /memory pause — pause learning for this session
• /memory why — explain what shaped the previous response

Set your Anthropic API key in the keychain so the consolidator can extract facts from your turns:

python3 -c 'import keyring; keyring.set_password("deep-context", "anthropic", "sk-ant-…")'

Anything that speaks the OpenAI Chat Completions API. Start the proxy:

uv run dc-proxy             # listens on port 7480

Point your tool at it:

# Codex CLI
export OPENAI_BASE_URL=http://127.0.0.1:7480
codex

# Cursor — Settings → Models → Override URL: http://127.0.0.1:7480
# Aider — aider --openai-api-base http://127.0.0.1:7480
# Continue.dev — config.json → "apiBase": "http://127.0.0.1:7480"

The proxy injects surfaced memory into the system message, forwards your request to the real OpenAI (or any compatible upstream), streams the response back, and captures the completed turn for consolidation. The upstream provider never sees the injected memory marker — it looks like any other system instruction.

For consolidator extraction with this adapter, set your OpenAI key:

python3 -c 'import keyring; keyring.set_password("deep-context", "openai", "sk-…")'

Two paths depending on what you want:

Speed-first — llama-server passthrough:

# 1. Run llama-server yourself (or use Ollama, LM Studio, etc.)
llama-server -m qwen2.5-7b.gguf --port 8080

# 2. Point dc-local-llm at it
DC_INFERENCE_BACKEND=llama_cpp DC_LLAMA_BASE_URL=http://127.0.0.1:8080 \
  uv run dc-local-llm

Your model is now served at http://127.0.0.1:7475/v1/chat/completions with memory injection.

Deep-context mode — PyTorch + forward hooks (requires ≥16GB unified memory or ≥12GB VRAM):

uv sync --extra inference
DC_MODEL_ID=Qwen/Qwen2.5-7B-Instruct uv run dc-local-llm

This path captures the model's hidden states mid-generation, so the surfacing brain can see what the model is currently "thinking about" and inject relevant memory at the token level, not just per turn. Slower per token, dramatically more accurate surfacing.

Either way, point your client at the local endpoint:

export OPENAI_BASE_URL=http://127.0.0.1:7475

Run all three adapters at once. They share the same memory store. A fact learned in Cursor surfaces in Claude Code. A correction in Aider updates the memory the local Qwen sees next.

uv run dc-daemon &       # core daemon, port 7472
uv run dc-proxy &        # OpenAI-compatible adapter, port 7480
uv run dc-local-llm &    # local model adapter, port 7475
# Claude Code plugin attaches via hooks (no separate process)

Three tiers govern what reaches your model:

• Priority — pinned facts that load every turn. Identity ("uses pnpm"), conventions ("no default exports"), active project context. Loaded unconditionally, capped at 8.
• Working — facts surfaced by the Predictor based on your current prompt. Embedded, vector-searched, optionally reranked with bge-reranker-v2-m3. Typically 1–4 per turn.
• Archival — everything else. Stored but inactive. Promoted into Working when relevance returns.

A forgetting policy (slow / balanced / aggressive) prunes archival memories on a time-decay + value-score basis. Contradictions automatically supersede older facts. You can pin, forget, or edit anything from the CLI:

dc memory list
dc memory pin "Always use uv, never pip directly"
dc memory show mem_01KRF3758QQW52H6EQ0YR1W28J
dc memory forget mem_01KRF3758QQW52H6EQ0YR1W28J
dc inspect why                    # what shaped the last turn
dc logs tail --filter memory      # live event stream

Local-first. The daemon runs on your machine. Memory and embeddings live in a single SQLite file under ~/Library/Application Support/DeepContext/ (macOS) or ~/.local/share/deep-context/ (Linux). API keys live in the OS keychain. The only network calls are to whichever upstream LLM provider you've configured (Anthropic for the consolidator, OpenAI through the proxy, etc.) — the daemon itself phones nobody home.

Cross-machine sync is optional and end-to-end encrypted. A self-hostable relay (uv run dc-relay) accepts opaque ciphertext envelopes and replays them to your devices. The relay can't read your memory; only devices holding the account's X25519 private key can decrypt.

Inspect everything that's stored at http://127.0.0.1:7472/inspect. Export at any time with dc export. Wipe everything with dc reset all --yes.

The daemon detects your tier at startup and surfaces it in dc status. Features that need more hardware than you have are explicitly disabled with a clear reason — they never silently degrade.

Four-layer hexagonal split:

L4  dc-infra        SQLite + sqlite-vec, embedders, keystore, schedulers,
                    crypto, runtimes, training pipelines
L3  dc-core/ports   Protocol definitions for every external system
L2  dc-core/usecases  Pure async functions over the domain
L1  dc-core/domain  Pure dataclasses, zero infrastructure imports

• dc-daemon wires it all up and serves the HTTP + WebSocket protocol.
• dc-cli is the dc command.
• dc-claude-plugin ships the Claude Code hooks + MCP server.
• dc-proxy is the OpenAI-compatible proxy adapter.
• dc-relay is the self-hostable sync relay.

The daemon's API surface (http://127.0.0.1:7472/docs when running) is the only public contract between layers. Adapters speak HTTP + WebSocket; nothing else.

The core daemon, CLI, Claude Code plugin, OpenAI proxy, local-model runtime, memory tiering, consolidation, learned surfacing, LoRA training pipeline, and cross-machine sync are all implemented and tested.

Active follow-up work, gated on real-hardware dogfood:

• Real-runtime integration of mid-stream injection and KV cache splice on a loaded transformer
• In-Place TTT optimizer step inside the streaming generation loop
• Native macOS app (the existing Tauri GUI is functional but a SwiftUI rewrite is planned)

The daemon reads config.toml from the OS config directory. Defaults are sensible; the file is optional. See spec/config-schema.md for the full schema.

[transport]
host = "127.0.0.1"
port = 7472

[learning]
aggressiveness = "balanced"      # conservative | balanced | aggressive
forgetting     = "balanced"      # slow | balanced | aggressive
cross_tool_memory = true

[consolidator]
backend = "auto"                 # auto | anthropic | openai | ollama

[embedding]
model = "sentence-transformers/all-mpnet-base-v2"

[privacy]
encryption_at_rest = true
telemetry          = false

[sync]
enabled   = false
relay_url = "http://127.0.0.1:7479"

Apache-2.0 licensed. DCO sign-off required on every commit (git commit -s). See CONTRIBUTING.md for the full guide, SECURITY.md for private vulnerability disclosure, and GOVERNANCE.md for how decisions get made.

The codebase enforces strict architecture layering via import-linter. Pull requests that violate the four-layer split are rejected by CI. Tests run on Python 3.11 and 3.12, macOS and Ubuntu.

Apache License 2.0. See LICENSE.