ContextFS

Universal AI Memory Layer - Cross-client, cross-repo context management with RAG.

Works with Claude Code, Claude Desktop, Gemini CLI, Codex CLI, and any MCP client.

Documentation | Developer Memory Workflow Guide | GitHub

Features

• Semantic Search - ChromaDB + sentence-transformers for intelligent retrieval
• Auto Code Indexing - Automatically index repositories for semantic code search
• Dual Storage - Smart routing between FTS (keywords) and RAG (semantic)
• Cross-Repo Memory - Memories track source repository automatically
• Session Management - Automatic capture and replay of conversation context
• MCP Server - Standard protocol for universal client support
• Plugins - Native integrations for Claude Code, Gemini CLI, Codex CLI
• Web UI - Browse and search memories with side-by-side FTS/RAG comparison

Quick Start

# Run with uvx (no install needed)
uvx contextfs --help
uvx contextfs-mcp  # Start MCP server

# Or install with pip
pip install contextfs

# Or install with uv
uv pip install contextfs

# Or install from source
git clone https://github.com/MagnetonIO/contextfs.git
cd contextfs
pip install -e .

Upgrading

# Upgrade with pip
pip install --upgrade contextfs

# Upgrade with uv
uv pip install --upgrade contextfs

# Upgrade with uvx (automatic on next run)
uvx --upgrade contextfs --help

Usage

CLI

# Save memories
contextfs save "Use PostgreSQL for the database" --type decision --tags db,architecture
contextfs save "API uses snake_case keys" --type fact --tags api,style

# Search
contextfs search "database decisions"
contextfs search "api conventions" --type fact

# Recall specific memory
contextfs recall abc123

# List recent
contextfs list --limit 20 --type decision

# Sessions
contextfs sessions

Python API

from contextfs import ContextFS, MemoryType

ctx = ContextFS()

# Save
ctx.save(
    "Use JWT for authentication",
    type=MemoryType.DECISION,
    tags=["auth", "security"],
)

# Search
results = ctx.search("authentication")
for r in results:
    print(f"[{r.score:.2f}] {r.memory.content}")

# Get context for a task
context = ctx.get_context_for_task("implement login")
# Returns formatted strings ready for prompt injection

MCP Server

Add to your MCP client config (Claude Code, Claude Desktop):

{
  "mcpServers": {
    "contextfs": {
      "command": "uvx",
      "args": ["contextfs-mcp"]
    }
  }
}

Or with Python directly:

{
  "mcpServers": {
    "contextfs": {
      "command": "python",
      "args": ["-m", "contextfs.mcp_server"]
    }
  }
}

MCP Tools:

MCP Prompts:

Plugins

Claude Code

# Install hooks for automatic context capture
python -c "from contextfs.plugins.claude_code import install_claude_code; install_claude_code()"

Gemini CLI / Codex CLI

from contextfs.plugins.gemini import install_gemini
from contextfs.plugins.codex import install_codex

install_gemini()  # For Gemini CLI
install_codex()   # For Codex CLI

Cross-Repo Namespaces

ContextFS automatically detects your git repository and isolates memories:

# In repo A
ctx = ContextFS()  # namespace = "repo-<hash-of-repo-a>"
ctx.save("Repo A specific fact")

# In repo B
ctx = ContextFS()  # namespace = "repo-<hash-of-repo-b>"
# Won't see Repo A's memories

# Global namespace (shared across repos)
ctx = ContextFS(namespace_id="global")
ctx.save("Shared across all repos")

Configuration

Environment variables:

CONTEXTFS_DATA_DIR=~/.contextfs
CONTEXTFS_EMBEDDING_MODEL=all-MiniLM-L6-v2
CONTEXTFS_CHUNK_SIZE=1000
CONTEXTFS_DEFAULT_SEARCH_LIMIT=10
CONTEXTFS_AUTO_SAVE_SESSIONS=true
CONTEXTFS_AUTO_LOAD_ON_STARTUP=true

Supported Languages

ContextFS supports 50+ file types including Python, JavaScript, TypeScript, Go, Rust, Java, C++, and more. See full list in docs.

Developer Memory Workflow (DMW)

ContextFS enables persistent developer memory across sessions with typed memories:

See the full Developer Memory Workflow Guide for patterns and examples.

Memory Lineage & Graph Operations

ContextFS tracks memory evolution and relationships with graph-backed lineage:

# Evolve memory (update with history tracking)
contextfs evolve <id> "Updated content" --summary "Why it changed"

# View lineage (ancestors/descendants)
contextfs lineage <id> --direction both

# Merge multiple memories
contextfs merge <id1> <id2> --summary "Combined knowledge" --strategy union

# Split memory into parts
contextfs split <id> "Part 1" "Part 2" --summaries "First|Second"

# Link related memories
contextfs link <id1> <id2> references --bidirectional

# Find connected memories
contextfs related <id> --depth 2

MCP Tools for Graph Operations:

Relationship Types: references, depends_on, contradicts, supports, supersedes, related_to, derived_from, part_of, implements

Session Management

# List sessions
contextfs sessions

# Save current session
contextfs save --save-session current --label "feature-auth"

# Load session context
contextfs load-session <session_id>

Source tool auto-detected (claude-code, claude-desktop) or set via CONTEXTFS_SOURCE_TOOL.

Web UI

Start the web server to browse and search memories:

contextfs web
# Opens at http://localhost:8000

contextfs web --port 3000  # Custom port

Features:

• Browse all memories with filtering by type, repo, and project
• Side-by-side FTS vs RAG search comparison
• Session browser and message viewer
• Real-time memory statistics

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        ContextFS Core                             │
├──────────────────────────────────────────────────────────────────┤
│   ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐                  │
│   │  CLI  │   │  MCP  │   │ Web UI│   │Python │                  │
│   │       │   │Server │   │       │   │  API  │                  │
│   └───┬───┘   └───┬───┘   └───┬───┘   └───┬───┘                  │
│       └───────────┴─────┬─────┴───────────┘                      │
│                         │                                         │
│                 ┌───────▼───────┐                                 │
│                 │  ContextFS()  │                                 │
│                 │   core.py     │                                 │
│                 └───────┬───────┘                                 │
│                         │                                         │
│         ┌───────────────┼───────────────┐                         │
│         │               │               │                         │
│ ┌───────▼───────┐ ┌─────▼─────┐ ┌───────▼───────┐                │
│ │MemoryLineage  │ │StorageRouter│ │ AutoIndexer │                │
│ │(Graph Ops)    │ │           │ │ (Code Index) │                 │
│ └───────┬───────┘ └─────┬─────┘ └───────────────┘                │
│         │               │                                         │
│         │       ┌───────▼───────┐                                 │
│         │       │TypedStorage   │ ← EdgeRelation, MemoryEdge     │
│         │       │   Protocol    │   GraphPath, GraphTraversal    │
│         │       └───────┬───────┘                                 │
│         │               │                                         │
│         └───────┬───────┼───────┬───────────────┐                │
│                 │       │       │               │                 │
│         ┌───────▼──┐ ┌──▼───┐ ┌─▼────────┐ ┌────▼─────┐          │
│         │ SQLite   │ │Chroma│ │PostgreSQL│ │ FalkorDB │          │
│         │ + FTS5   │ │  DB  │ │ +pgvector│ │ (Cypher) │          │
│         │(default) │ │(RAG) │ │ (hosted) │ │ (graph)  │          │
│         └──────────┘ └──────┘ └──────────┘ └──────────┘          │
└──────────────────────────────────────────────────────────────────┘

Storage Backends

Typed Storage Protocol

The StorageProtocol provides a unified interface across backends with typed models:

• EdgeRelation - 20+ relationship types (references, depends_on, contradicts, etc.)
• MemoryEdge - Typed edges with weights and metadata
• GraphPath / GraphTraversal - Path finding and subgraph queries

License

MIT

Authors

Matthew Long and The YonedaAI Collaboration