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.

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

What It Does

Feature	Description
Cross-session Memory	Record and retrieve learnings across sessions with semantic search
Checkpoints	Save and resume context snapshots before hitting limits
Context-Folding	Isolate complex sub-tasks with dedicated token budgets
Error Remediation	Track error patterns and fixes - never solve the same bug twice
Repository Search	Semantic code search over your indexed codebase
Self-Reflection	Analyze behavior patterns and improve documentation
Secret Scrubbing	Automatic detection and removal via gitleaks

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)

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:

Platform	Architecture	File
macOS	Apple Silicon	`contextd_*_darwin_arm64.tar.gz`
macOS	Intel	`contextd_*_darwin_amd64.tar.gz`
Linux	x64	`contextd_*_linux_amd64.tar.gz`
Windows	x64	`contextd_*_windows_amd64.tar.gz`

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"

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:

Tenant ID - Derived from git remote URL (e.g., github.com/username)
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

Command	Description
`/contextd-init`	Initialize contextd for a new project
`/contextd-checkpoint`	Save session checkpoint
`/contextd-search`	Search memories and remediations
`/contextd-remember`	Record a learning or insight
`/contextd-diagnose`	AI-powered error diagnosis
`/contextd-reflect`	Analyze behavior patterns and improve docs
`/contextd-status`	Show contextd status
`/contextd-consensus-review`	Multi-agent code review
`/contextd-help`	Show available commands and skills

Plugin Skills

Skill	Use When
`using-contextd`	Starting any session - overview of all tools
`session-lifecycle`	Session start/end protocols
`cross-session-memory`	Learning loop (search → do → record → feedback)
`checkpoint-workflow`	Context approaching 70% capacity
`error-remediation`	Resolving errors systematically
`repository-search`	Semantic code search
`self-reflection`	Reviewing behavior patterns, improving docs
`writing-claude-md`	Creating effective CLAUDE.md files
`secret-scrubbing`	Understanding secret detection
`project-onboarding`	Onboarding to new projects
`consensus-review`	Multi-agent code review with specialized reviewers

MCP Tools

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

Memory

Tool	Purpose
`memory_search`	Find relevant strategies from past sessions
`memory_record`	Save a new learning or strategy
`memory_feedback`	Rate whether a memory was helpful
`memory_outcome`	Report task success/failure after using a memory
`memory_consolidate`	Merge related memories into refined summaries
`memory_consolidate_session`	Consolidate specific memories by ID

Checkpoints

Tool	Purpose
`checkpoint_save`	Save current context for later
`checkpoint_list`	List available checkpoints
`checkpoint_resume`	Resume from a saved checkpoint

Remediation

Tool	Purpose
`remediation_search`	Find fixes for similar errors
`remediation_record`	Record a new error fix
`remediation_feedback`	Rate whether a fix was helpful
`troubleshoot_diagnose`	AI-powered error diagnosis

Repository & Search

Tool	Purpose
`semantic_search`	Smart search with semantic understanding + grep fallback
`repository_index`	Index a codebase for semantic search
`repository_search`	Semantic search over indexed code

Context-Folding

Tool	Purpose
`branch_create`	Create isolated context branch with token budget
`branch_return`	Return from branch with scrubbed results
`branch_status`	Get branch status and budget usage

Conversation

Tool	Purpose
`conversation_index`	Index Claude Code conversation files
`conversation_search`	Search past conversations for decisions and context

Reflection

Tool	Purpose
`reflect_report`	Generate self-reflection report on memories and patterns
`reflect_analyze`	Analyze behavioral patterns across sessions

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

Scope	Description	Example
TenantID	Organization/user identifier	`github.com/acme-corp`
TeamID	Team within organization	`platform`
ProjectID	Project within team	`contextd`

Security Guarantees

Behavior	Description
Fail-closed	Operations without tenant context return errors
Filter injection blocked	Users cannot override tenant filters
Metadata enforced	Tenant fields always set from authenticated context

Automatic Detection

ContextD automatically detects tenant context from git:

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

No manual configuration needed for single-user deployments.

Advanced Configuration

Environment Variables

Variable	Default	Description
`VECTORSTORE_PROVIDER`	`chromem`	Vector store (`chromem` or `qdrant`)
`VECTORSTORE_PATH`	`~/.config/contextd/vectorstore`	Data storage path
`QDRANT_HOST`	`localhost`	Qdrant host (if using qdrant)
`QDRANT_PORT`	`6334`	Qdrant gRPC port
`EMBEDDING_PROVIDER`	`fastembed`	Embedding provider
`LOG_LEVEL`	`info`	Log level (debug, info, warn, error)

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"
      }
    }
  }
}

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 ~/

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

Check settings.json syntax (valid JSON?)
Verify the path to contextd is correct
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.

CLI Tools

ContextD includes two binaries:

Binary	Purpose
`contextd`	MCP server (run with `--mcp --no-http`)
`ctxd`	CLI utility for manual operations

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

Community

Join the FyrsmithLabs Discord to ask questions, share feedback, and connect with other users and contributors.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Write tests for new functionality
Submit a pull request

License

MIT License - See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 348 Commits
.claude		.claude
.github		.github
Formula		Formula
cmd		cmd
deploy		deploy
docs		docs
examples		examples
grafana		grafana
internal		internal
pkg/api/v1		pkg/api/v1
scripts		scripts
test		test
.air.toml		.air.toml
.claude_settings.json		.claude_settings.json
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.goreleaser-linux.yaml		.goreleaser-linux.yaml
.goreleaser.yaml		.goreleaser.yaml
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.goreleaser		Dockerfile.goreleaser
Dockerfile.integration		Dockerfile.integration
Dockerfile.validation		Dockerfile.validation
LICENSE.md		LICENSE.md
Makefile		Makefile
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
VERSION		VERSION
config.example.yaml		config.example.yaml
docker-compose.integration.yml		docker-compose.integration.yml
docker-compose.validation.yml		docker-compose.validation.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

ContextD

⚠️ Alpha Status

Prerequisites

What It Does

Data Privacy & Security

Quick Start

Option 1: Automated Plugin Setup (Easiest)

Option 2: Homebrew (macOS/Linux)

Option 3: Chocolatey (Windows)

Option 4: Download Binary

Configuration

Automated (Recommended)

Manual Configuration

Claude Desktop App (Alternative)

Verify Setup

First Run Behavior

Project Identification

Daily Workflow

Plugin Commands

Plugin Skills

MCP Tools

Memory

Checkpoints

Remediation

Repository & Search

Context-Folding

Conversation

Reflection

How It Works

Multi-Tenancy

How It Works

Tenant Hierarchy

Security Guarantees

Automatic Detection

Advanced Configuration

Environment Variables

Using External Qdrant

Data & Backup

Troubleshooting

"contextd not found" after installation

MCP server not connecting

First run is slow

"permission denied" errors

Still stuck?

CLI Tools

ctxd Commands

Building from Source

Documentation

Community

Contributing

License

Links

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 25

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages