ContextD

Cross-session memory and context management for AI agents.

ContextD helps AI coding assistants remember what works, learn from mistakes, and maintain context across sessions. It's designed for developers who want their AI tools to get smarter over time.

⚠️ Alpha Status

This project is in active alpha development. Features and APIs change frequently as we refine the product based on user feedback.

• ✅ Core functionality is stable and tested
• ⚠️ Breaking changes are generally avoided but can still occur
• 📝 We document all changes in release notes
• 🚀 Expect rapid iteration and improvements

If you encounter issues, please report them on GitHub.

What It Does

Data Privacy & Security

All data stays local on your machine.

• No data is sent to external servers
• Memories and checkpoints stored in ~/.config/contextd/
• Embeddings generated locally using ONNX (no API calls)
• Secrets automatically scrubbed from all tool responses using gitleaks
• Git integration uses local repository info only (remote URL for project identification)

First Run Behavior

On first run, contextd automatically downloads required dependencies:

ONNX runtime not found. Downloading v1.23.0...
Downloaded to ~/.config/contextd/lib/libonnxruntime.so
Downloading fast-bge-small-en-v1.5...

This one-time download (~100MB) happens automatically. Subsequent runs start instantly.

Project Identification

ContextD automatically identifies your project using git:

1. Tenant ID - Derived from git remote URL (e.g., github.com/username)
2. Project ID - Derived from repository name

This means:

• Different repositories have isolated memories
• Forked repos share tenant but have separate project memories
• Non-git directories use a fallback identifier

No configuration needed - it works automatically based on your current directory.

Daily Workflow

After installation, here's how to use contextd:

1. Session Start
   └─→ Memories auto-searched, checkpoints listed
   └─→ Resume from checkpoint if offered

2. During Work
   └─→ /contextd-search <topic>     Find relevant memories
   └─→ /contextd-diagnose <error>   Get help with errors
   └─→ Semantic search with repository_search()

3. Task Complete
   └─→ /contextd-remember           Record what you learned

4. Context High (70%+)
   └─→ /contextd-checkpoint         Save session state
   └─→ /clear                       Reset context
   └─→ Resume with /contextd-checkpoint

5. New Project
   └─→ /contextd-init               Setup new project

Plugin Commands

Note: As of v0.4.0, plugin commands are in fyrsmithlabs/marketplace. Install with claude plugins add fyrsmithlabs/marketplace

Plugin Skills

MCP Tools

ContextD exposes 25 tools to Claude Code, organized by category:

Memory

Checkpoints

Remediation

Repository & Search

Context-Folding

Conversation

Reflection

How It Works

┌─────────────────────────────────────────────────────────────┐
│                       Claude Code                            │
│                           │                                  │
│                      MCP Protocol                            │
│                           │                                  │
│  ┌────────────────────────▼────────────────────────────┐    │
│  │                     ContextD                         │    │
│  │                                                      │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │    │
│  │  │  Reasoning  │  │ Checkpoint  │  │ Remediation │  │    │
│  │  │    Bank     │  │   Service   │  │   Service   │  │    │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  │    │
│  │         │                │                │         │    │
│  │         └────────────────┼────────────────┘         │    │
│  │                          │                          │    │
│  │                   ┌──────▼──────┐                   │    │
│  │                   │   chromem   │  (embedded)       │    │
│  │                   │   Vectors   │  or Qdrant        │    │
│  │                   └─────────────┘                   │    │
│  │                                                      │    │
│  │  + FastEmbed (local ONNX embeddings)                │    │
│  │  + gitleaks (secret scrubbing)                      │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Key components:

• chromem - Embedded vector database (zero external dependencies)
• FastEmbed - Local ONNX embeddings (no API calls required)
• gitleaks - Secret detection and scrubbing
• Optional Qdrant - External vector database for larger deployments

Multi-Tenancy

ContextD uses payload-based tenant isolation to ensure data separation between organizations, teams, and projects.

How It Works

• All documents stored in shared collections with tenant metadata
• Queries automatically filtered by tenant context
• Missing tenant context returns an error (fail-closed security)

Tenant Hierarchy

Security Guarantees

Automatic Detection

ContextD automatically detects tenant context from git:

1. TenantID - Derived from git remote URL (e.g., github.com/username)
2. ProjectID - Derived from repository name

No manual configuration needed for single-user deployments.

Data & Backup

Data is stored in ~/.config/contextd/ by default:

~/.config/contextd/
├── vectorstore/          # Memories, checkpoints, remediations
├── lib/                  # ONNX runtime (auto-downloaded)
└── config.yaml           # Optional config file

Backup:

tar czf contextd-backup.tar.gz ~/.config/contextd/

Restore:

tar xzf contextd-backup.tar.gz -C ~/

CLI Tools

ContextD includes two binaries:

ctxd Commands

# MCP Configuration (NEW)
ctxd mcp install         # Auto-configure MCP server settings
ctxd mcp status          # Verify MCP configuration
ctxd mcp uninstall       # Remove MCP configuration

# Statusline
ctxd statusline install  # Configure Claude Code statusline
ctxd statusline run      # Run statusline (used by Claude Code)

# Utilities
ctxd health              # Check server health
ctxd scrub <file>        # Scrub secrets from a file
ctxd init                # Initialize dependencies (ONNX runtime)
ctxd migrate             # Migrate data from Qdrant to chromem

Building from Source

git clone https://github.com/fyrsmithlabs/contextd.git
cd contextd

# Build with FastEmbed (requires CGO)
make build

# Or install to $GOPATH/bin
make go-install

# Run tests
make test

Documentation

• Docker Setup - Running contextd in Docker
• Configuration - Full configuration reference
• Troubleshooting - Common issues and solutions
• Architecture - Technical architecture
• Design Plans - Feature design documents
• Specifications - Technical specifications

Links

• GitHub Repository
• Releases
• Docker Image
• Homebrew Formula
• Issues
• Discord

Prerequisites

You need Claude Code installed first.

Claude Code is Anthropic's AI coding assistant. ContextD extends Claude Code with persistent memory via the MCP (Model Context Protocol) server integration.

Install Claude Code:

# macOS/Linux
curl -fsSL https://claude.ai/install.sh | bash

# Or visit: https://claude.ai/download

Verify installation:

claude --version

Quick Start

Choose one of the following installation methods:

Option 1: Automated Plugin Setup (Easiest)

If you already have Claude Code installed:

# 1. Install the plugin (adds skills, commands, agents)
claude plugins add fyrsmithlabs/marketplace

# 2. Run auto-setup in Claude Code
/contextd-init

This automatically:

• ✅ Downloads contextd binary (or uses Docker if unavailable)
• ✅ Configures MCP settings in ~/.claude/settings.json
• ✅ Validates the connection

Restart Claude Code and verify:

# In Claude Code, type:
/mcp
# Should show "✓ contextd - connected"

That's it! See ONBOARDING.md for a guided tutorial.

Option 2: Homebrew (macOS/Linux)

# Add the tap and install
brew tap fyrsmithlabs/contextd https://github.com/fyrsmithlabs/contextd
brew install contextd

Then add the MCP configuration (see Configuration below).

Option 3: Chocolatey (Windows)

choco install contextd

Then add the MCP configuration (see Configuration below).

Note: Windows builds use pure Go (no CGO). Local ONNX embeddings are not available; configure a remote embedding provider or use the default.

Option 4: Download Binary

Download from GitHub Releases:

Extract and install:

# Extract
tar xzf contextd_*.tar.gz

# Move to PATH (choose one)
mv contextd ~/.local/bin/       # User install
# OR
sudo mv contextd /usr/local/bin/  # System install

Then add the MCP configuration (see Configuration below).

Configuration

Automated (Recommended)

Use the CLI tool for automatic configuration:

ctxd mcp install    # Auto-configure MCP settings
ctxd mcp status     # Verify configuration
ctxd mcp uninstall  # Remove configuration

Or use the plugin init command in Claude Code: /contextd-init

Manual Configuration

If you prefer manual setup, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "contextd": {
      "type": "stdio",
      "command": "contextd",
      "args": ["--mcp", "--no-http"]
    }
  }
}

Note: If the file doesn't exist, create it with just this content.

Claude Desktop App (Alternative)

If using the Claude Desktop app instead of Claude Code CLI:

macOS/Linux: ~/.claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "contextd": {
      "command": "contextd",
      "args": ["--mcp", "--no-http"]
    }
  }
}

Verify Setup

After adding configuration, restart Claude Code and verify:

# Check MCP connection (in Claude Code)
/mcp
# Should show: contextd - connected

# Or test a tool
# In conversation: "Use memory_search to check for existing memories"

Advanced Configuration

Environment Variables

Using External Qdrant

For larger deployments or team use:

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  -v $(pwd)/qdrant_data:/qdrant/storage \
  qdrant/qdrant

Configure in ~/.claude/settings.json:

{
  "mcpServers": {
    "contextd": {
      "type": "stdio",
      "command": "contextd",
      "args": ["--mcp", "--no-http"],
      "env": {
        "VECTORSTORE_PROVIDER": "qdrant",
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6334"
      }
    }
  }
}

Troubleshooting

"contextd not found" after installation

Ensure the binary is in your PATH:

# Check if contextd is found
which contextd

# If not, add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

MCP server not connecting

1. Check settings.json syntax (valid JSON?)
2. Verify the path to contextd is correct
3. Restart Claude Code after config changes

# Test manually
contextd --version
contextd --mcp --no-http  # Should start without errors

First run is slow

Expected behavior - contextd downloads ONNX runtime (~50MB) and embedding model (~50MB) on first run. This only happens once.

"permission denied" errors

chmod +x ~/.local/bin/contextd

Still stuck?

See docs/troubleshooting.md or open an issue.

License

MIT License - See LICENSE for details.