contextd

ContextD

⚠️ ALPHA - This project is in active development. APIs may change.

A developer-first AI context and reasoning engine.

Note: This README describes our vision and roadmap. See Current Status for what's implemented today.

Vision

ContextD is designed to eliminate the complexity of building with AI. It gives teams a smart baseline for context management, organizational memory, and workflow-aware reasoning—without forcing them into rigid pipelines or spending weeks learning prompts, agents, and skills.

This is not RAG. It's a self-improving system that learns how your team actually works, helping developers get real value from AI faster, safer, and with far less friction.

Core Principles

• Developer-first: Works with your existing tools, not against them
• Zero lock-in: Runs locally, on-prem, or in the cloud
• Self-improving: Learns from successes and failures to get better over time
• Privacy-conscious: Your data stays yours; secrets are automatically scrubbed

Current Status

ContextD is in active development. Here's what works today:

Implemented

Roadmap

Quick Start

Using Docker (Recommended)

The Docker image includes everything: ContextD, Qdrant, and FastEmbed embeddings.

# Pull the image (multi-arch: amd64 and arm64)
docker pull ghcr.io/fyrsmithlabs/contextd:0.1.0-alpha

Add to your Claude Code MCP config (~/.claude.json or Claude Desktop config):

{
  "mcpServers": {
    "contextd": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "contextd-data:/data",
        "ghcr.io/fyrsmithlabs/contextd:0.1.0-alpha"
      ]
    }
  }
}

Restart Claude Code. That's it.

Using Homebrew (macOS/Linux)

brew install fyrsmithlabs/tap/contextd

Or tap first:

brew tap fyrsmithlabs/homebrew-tap
brew install contextd

Start Qdrant (required for vector search):

docker run -d --name contextd-qdrant \
  -p 6333:6333 -p 6334:6334 \
  -v contextd-qdrant-data:/qdrant/storage \
  --restart always \
  qdrant/qdrant:v1.12.1

Add to Claude Code MCP config (~/.claude.json):

{
  "mcpServers": {
    "contextd": {
      "command": "contextd",
      "args": ["-mcp"],
      "env": {
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6334"
      }
    }
  }
}

Note: Homebrew binaries use the TEI embedding provider by default. Set TEI_URL if you have a TEI server, or use the Docker image for built-in FastEmbed support.

Download Binary

Download from GitHub Releases:

Note: Pre-built binaries use TEI for embeddings (no CGO). For FastEmbed support, use Docker or build from source with CGO enabled.

Building from Source

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

# Without CGO (uses TEI for embeddings)
go build -o contextd ./cmd/contextd
go build -o ctxd ./cmd/ctxd

# With CGO + FastEmbed (requires ONNX runtime)
CGO_ENABLED=1 go build -o contextd ./cmd/contextd

Docker Image Tags

Multi-arch support: linux/amd64 and linux/arm64

# Explicit platform
docker pull --platform linux/arm64 ghcr.io/fyrsmithlabs/contextd:0.1.0-alpha

MCP Tools

ContextD exposes these tools to Claude Code:

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Claude Code                          │
│                         │                                │
│                    MCP Protocol                          │
│                         │                                │
│  ┌──────────────────────▼──────────────────────────┐    │
│  │                  ContextD                        │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │    │
│  │  │ Reasoning   │  │ Checkpoint  │  │ Remediate│ │    │
│  │  │ Bank        │  │ Service     │  │ Service  │ │    │
│  │  └──────┬──────┘  └──────┬──────┘  └────┬─────┘ │    │
│  │         │                │               │       │    │
│  │         └────────────────┼───────────────┘       │    │
│  │                          │                       │    │
│  │                   ┌──────▼──────┐                │    │
│  │                   │   Qdrant    │                │    │
│  │                   │  (Vectors)  │                │    │
│  │                   └─────────────┘                │    │
│  └──────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

All-in-one container includes:

• ContextD MCP server
• Qdrant vector database
• FastEmbed for local embeddings (ONNX-based, no API calls)

Data Persistence

All data persists in a Docker volume:

# Backup
docker run --rm -v contextd-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/contextd-backup.tar.gz /data

# Restore
docker run --rm -v contextd-data:/data -v $(pwd):/backup alpine \
  tar xzf /backup/contextd-backup.tar.gz -C /

Documentation

See the docs/ directory for detailed documentation:

• Architecture Overview - System design and component interactions
• Configuration Reference - Environment variables and settings
• MCP Tools API - Complete tool reference with examples
• Troubleshooting Guide - Common issues and solutions
• Contributing Guide - How to contribute to ContextD

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development setup
• Coding standards
• Testing requirements
• Pull request process

License

MIT License - See LICENSE for details.

Links

• GitHub Repository
• GitHub Releases
• Docker Image
• Homebrew Tap
• Issue Tracker