[!NOTE] Pre-1.0, but built for daily use. Context Fabric is actively used, tested, and released regularly. APIs and storage formats may still evolve before 1.0, so pin versions and review the CHANGELOG before upgrading.

Start Here

• Want to try it fast? Go to Quick Start
• Need a client config? Open CLI Setup
• Want the full tool surface? See Tools Reference
• Prefer guided docs? Browse the Wiki

Why it exists

Coding agents are great in-session and forgetful between sessions. Important context disappears when the terminal closes: decisions, debugging discoveries, codebase conventions, partial work, and the answer to "what changed since I was last here?"

Context Fabric gives MCP-compatible coding agents a persistent memory layer that stays local, searchable, and useful.

Who it's for

• Developers using MCP-capable coding tools like Claude Code, Cursor, Codex CLI, Gemini CLI, OpenCode, or Kimi
• Teams that want persistent agent memory without sending code and context to a hosted memory service
• Builders who want a lightweight local memory substrate instead of wiring up a separate vector database stack

Why Context Fabric

• Local-first by design — SQLite storage, local embeddings, Docker/local deployment, zero cloud dependency.
• Built for coding agents — remembers decisions, bug fixes, conventions, code patterns, and current project state.
• MCP-native — works as a real MCP server with Tools, Resources, and Prompts.
• Code-aware and time-aware — semantic code search, symbol indexing, and orientation around offline gaps.
• Practical to adopt — no external vector database, no API key, no hosted control plane required.

What you get

Memory & retrieval

• Three-layer memory — Working (L1), Project (L2), Semantic (L3). Memories auto-route to the right layer.
• Hybrid search — FTS5 BM25 + vector cosine + Reciprocal Rank Fusion. Query-side instruction prefixes applied automatically per embedder family (BGE, E5, MiniLM). Sub-100 ms p50 on 50K+ corpora.
• Semantic recall — in-process vector embeddings via ONNX + fastembed (bge-small-en-v1.5 by default, with one-env-var swap to larger models or GPU). No API keys needed.
• Bundled ANN — sqlite-vec ships as a regular dependency (since v0.13). KNN over the full corpus, graceful fallback if the loadable extension fails to attach.
• Optional CUDA inference — set CONTEXT_FABRIC_EMBED_EP=cuda + run scripts/setup-gpu.sh for ~30× ingest throughput on NVIDIA hardware.
• Local code indexing — scans source files, extracts symbols, and stays fresh via file watching.
• Time-aware orientation — "What changed while I was away?" with offline-gap detection and timezone support.
• Ghost messages — relevant memories surface via context.getCurrent without cluttering the main workflow.
• Public-benchmark harness — reproducible BEIR SciFact / FiQA and LongMemEval_S runners in benchmarks/public/.

Memory intelligence

• Provenance — structured citation blocks on memories (sessionId, eventId, filePath, commitSha, sourceUrl, and more).
• Dedup-on-store — cosine near-duplicate detection for L3 with skip, merge, or allow strategies.
• Bi-temporal memory — supersedes, validFrom, and validUntil support for "what was true at that time?" reasoning.

Agent ergonomics

• Skills — procedural memory with slugged, invokable instruction blocks and usage tracking.
• MCP Resources — browseable memory://skills, memory://recent, memory://conventions, memory://decisions, and templated resource views.
• MCP Prompts — slash-command workflows like cf-orient, cf-capture-decision, cf-review-session, cf-search-code, and cf-invoke-skill.
• context.importDocs — one-shot seeding from common onboarding docs like README.md, CHANGELOG.md, CONTRIBUTING.md, and AGENTS.md.
• Recall-quality harness — benchmark recall@k and MRR with npm run bench:quality.

Operations & DX

• 25 MCP tools — memory CRUD, recall/orientation, code search, docs import, backup/export/import, metrics/health, and 6 skill tools.
• Graceful shutdown — drains in-flight calls, checkpoints WAL, and closes cleanly.
• Data integrity — startup checks, explicit multi-row transactions, and online backups.
• Observability — structured logging plus context.metrics and context.health.
• Self-setup — context.setup can install Context Fabric into supported CLIs.
• Docker-first — easy docker run --rm -i transport with persistent named-volume storage.

Quick Start

Get running in a few minutes:

# 1. Clone and build the Docker image

git clone https://github.com/Abaddollyon/context-fabric.git
cd context-fabric
docker build -t context-fabric .

# 2. Verify the server responds

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | docker run --rm -i context-fabric

3. Add it to your CLI with the Docker transport:

docker run --rm -i -v context-fabric-data:/data/.context-fabric context-fabric

See CLI Setup for copy-paste configs for all supported CLIs, or let your AI do it once Context Fabric is reachable:

"Install and configure Context Fabric for Cursor using Docker"

git clone https://github.com/Abaddollyon/context-fabric.git
cd context-fabric
npm install
npm run build

Supported CLIs

[!TIP] Once Context Fabric is running in one MCP-capable tool, it can usually install itself into the others through context.setup.

What it feels like

Start a session and the agent orients itself:

It is 9:15 AM on Wednesday, Feb 25 (America/New_York).
Project: /home/user/myapp.
Last session: 14 hours ago. 3 new memories were added while you were away.

Store a decision once:

{ "type": "decision", "content": "Use Zod for all API validation. Schemas live in src/schemas/." }

Recall it naturally later:

{ "query": "how do we validate inputs?" }
// => "Use Zod for all API validation. Schemas live in src/schemas/."

No cloud account. No hidden service dependency. No need to re-explain the codebase every session.

Performance

Numbers on a commodity dev box (Ryzen 7 5800H + RTX 3060 12 GB, warm run, 2026-04-23):

Retrieval quality — public benchmarks

Reading this: On Recall@100 — the metric that matters for agent memory where an LLM reranks the recalled set — we match or beat OpenAI's text-embedding-3-small on both BEIR subsets, while remaining free, offline, and 100% local. See docs/benchmarks.md for the full methodology and reproduction commands.

Latency and throughput

Benchmark scripts: benchmarks/recall-latency.ts (npm run bench), benchmarks/public/ (npm run bench:beir:scifact, npm run bench:beir:fiqa, npm run bench:longmemeval:s).

Architecture at a glance

CLI (Claude Code, Cursor, Codex, etc.)
  |
  | MCP protocol (stdio / Docker)
  v
Context Fabric Server
  |-- Smart Router -----> L1: Working Memory   (in-memory, session-scoped)
  |-- Time Service        L2: Project Memory   (SQLite, per-project)
  |-- Code Index          L3: Semantic Memory  (SQLite + embeddings, cross-project)

Memories auto-route to the right layer. Scratchpad notes go to L1. Decisions and bug fixes go to L2. Reusable patterns and conventions go to L3. See Architecture for the full deep dive.

Documentation

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to get started.

License

MIT