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:

Tool	Description
contextfs_save	Save memory (auto-indexes repo, logs to session)
contextfs_search	Semantic search with cross-repo support
contextfs_recall	Get specific memory by ID
contextfs_list	List recent memories
contextfs_update	Update existing memory content, type, tags, or project
contextfs_delete	Delete a memory by ID
contextfs_init	Initialize repo for auto-indexing (opt-in)
contextfs_index	Index current repository for code search
contextfs_index_status	Check or cancel background indexing progress
contextfs_list_indexes	List all indexed repositories with stats
contextfs_list_repos	List all repositories with memories
contextfs_list_tools	List source tools (claude-code, claude-desktop, etc.)
contextfs_list_projects	List all projects
contextfs_sessions	List sessions
contextfs_load_session	Load session messages
contextfs_message	Add message to current session
contextfs_update_session	Update session label or summary
contextfs_delete_session	Delete a session and its messages
contextfs_import_conversation	Import JSON conversation as episodic memory

MCP Prompts:

Prompt	Description
contextfs-save-memory	Guided memory save with type selection
contextfs-init-repo	Initialize repo for auto-indexing
contextfs-index	Index repository for semantic search
contextfs-session-guide	Instructions for session capture
contextfs-save-session	Save current session

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:

Type	Use Case
fact	Project configurations, conventions
decision	Architectural choices with rationale
code	Algorithms, patterns, important snippets
error	Bug fixes, error patterns, solutions
procedural	Setup guides, deployment steps
episodic	Session transcripts, conversations

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:

Tool	Description
contextfs_evolve	Update memory with history tracking
contextfs_merge	Combine multiple memories into one
contextfs_split	Divide memory into separate parts
contextfs_link	Create relationships between memories
contextfs_related	Find connected memories via graph traversal
contextfs_lineage	View memory evolution history

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

Backend	Purpose
SQLite + FTS5	Default local storage, keyword search, sessions
ChromaDB	Vector embeddings, semantic/RAG search
PostgreSQL + pgvector	Hosted deployments, team sharing
FalkorDB	Advanced graph queries via Cypher

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