contextd

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