Context Wolf

License: MIT Python 3.12+ MCP pgvector

A high-performance local knowledge system for Claude Code via MCP integration. Stores decisions, code snippets, infrastructure details, and TODOs - so your AI assistant never forgets what you've already decided.

What it does

• Cross-Project Search - Full-text search + semantic vector search across all projects
• MCP Integration - 44 tools available directly in Claude Code sessions
• Notes - Long-form reference documents with tags and full-text search
• Snippets - Code snippet library with tags and type detection
• Infrastructure Tracking - Structured SSH host & service management
• TODO Lifecycle - Task tracking with priorities, categories, and status
• Now (sprint backlog) - Curated cross-project shortlist with WIP limits (today / week / later), can link to existing TODOs/notes/snippets and show their live status
• Git Integration - Post-commit hooks auto-track commits (opt-in per repo)
• Duplicate Detection - Warns at 85%+ similarity

Why?

Claude Code is brilliant - but it has amnesia. Every time a session ends, all context is gone. Next session, it suggests Cassandra when you decided on PostgreSQL two weeks ago.

ContextWolf fixes this. It runs as a local MCP server alongside Claude Code, storing decisions, code patterns, and infrastructure details in your own PostgreSQL database. When Claude starts a new session, the knowledge is still there.

How it works in practice

Day 1 - You're debugging an auth issue with Claude:

You: "Claude, save this: we decided to use session cookies instead of JWTs for security."
Claude calls context_save → decision stored in ContextWolf.

Day 14 - Fresh session, different feature:

You: "Claude, check what auth decisions we have before building the login route."
Claude calls context_search → finds your decision → implements session cookies, not JWTs.

No more repeating yourself. Your AI assistant finally has long-term memory.

How automatic is it? Claude sees the ContextWolf tools via MCP and can use them anytime. But it won't reliably do so on its own - even with instructions in CLAUDE.md. In practice, you'll sometimes need to say "save this in ContextWolf" or "check ContextWolf first". Think of it as a tool Claude can use, not one it always uses. The more you use it, the more natural the workflow becomes.

Why not just use Markdown files?

You could store context in .md files or CLAUDE.md. That works for small projects. But it doesn't scale:

• Search - Markdown files are loaded entirely into the context window. ContextWolf uses full-text search + vector similarity to return only relevant results.
• Cross-project - Markdown lives in one repo. ContextWolf searches across all your projects with one query.
• Scale - 7,000+ entries, search in ~1ms. A Markdown file with 1,000 lines costs tokens every time Claude reads it.
• Semantic search - Search for "authentication" and find entries about "JWT", "login", "OAuth". Markdown can't do that.
• Structure - Types, projects, tags, priorities, timestamps, duplicate detection. Not just free text.

Prerequisites

• Python 3.12+
• Docker (recommended for PostgreSQL) or an existing PostgreSQL 13+ with pgvector

Architecture

ContextWolf runs in two parts:

• PostgreSQL + pgvector (the storage) - one container, runs anywhere (local Docker, a Raspberry Pi, a NAS)
• cm-mcp (the MCP server) - always runs locally on your coding machine, launched by Claude Code via stdio

The optional GUI (context-wolf-ui) is a third component that reuses the same database - it never runs its own PostgreSQL instance.

Quick Start

git clone https://github.com/DarkWolfCave/context-wolf.git
cd context-wolf
cp .env.example .env
# Edit .env and set POSTGRES_PASSWORD
bash setup.sh

That's it. The setup script will:

1. Install uv (fast Python package manager) if needed
2. Install all dependencies
3. Start PostgreSQL via docker compose up -d (reads credentials from .env)
4. Write ~/.context/config.yaml (CLI config, same credentials as .env)
5. Download the ONNX embedding model (~90 MB, for semantic search)
6. Configure Claude Code MCP integration
7. Run diagnostics to verify everything works

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies (pick what you need)
uv sync                        # Core CLI + MCP server for Claude Code
uv sync --extra embeddings     # + Semantic search (ONNX, ~90 MB)
uv sync --extra all            # Everything

# Start PostgreSQL
cp .env.example .env
# edit .env, set POSTGRES_PASSWORD
docker compose up -d

# Configure CLI (reads .env for credentials)
cm init                        # Writes ~/.context/config.yaml

# Configure Claude Code
cm setup-mcp                   # Writes ~/.claude.json

# Check everything
cm doctor

Configuration files

Two files with identical credentials:

• .env - used by Docker Compose when starting PostgreSQL
• ~/.context/config.yaml - used by the CLI and MCP server to connect

cm init reads .env and writes config.yaml so both stay in sync. Change the password? Edit both files, restart the container, and run cm init again.

Data location

By default, PostgreSQL data is stored in ./data/postgres/ next to docker-compose.yml (the directory is gitignored). This makes the data easy to find, back up, or delete.

To store data elsewhere (e.g., in your home directory or on a separate SSD), edit the volumes: line in docker-compose.yml. Examples are in the comments at the top of that file.

Setup Script Options

bash setup.sh                  # Full interactive setup
bash setup.sh --install-only   # Only install dependencies
bash setup.sh --doctor         # Run diagnostics
bash setup.sh --init           # Configure database
bash setup.sh --setup-mcp      # Configure Claude Code MCP

Updating to a newer version

ContextWolf has no auto-updater - new versions don't reach your machine until you fetch them. From the repo directory:

git pull
bash setup.sh --install-only        # rebuilds the cm / cm-mcp / cm-embed tool

setup.sh --install-only runs uv tool install --reinstall, which forces uv to rebuild the wheel from the current source and replace the previous installation. (Plain --force is not enough - uv may reuse a cached wheel that still carries the old version.) After that:

• CLI (cm): the new commands are available immediately - check with cm --version.
• MCP server: restart Claude Code (or run /mcp and reconnect the context-manager server) so it loads the new code.
• Database schema: any new SQL migrations are applied automatically on the next cm call or MCP server start - no manual step needed.

If you only need the MCP tools updated (not the CLI), a Claude Code restart after git pull is enough, because the MCP server is launched directly from the repo via uv run. The CLI is the part that stays frozen until you reinstall it.

Database on a separate server

If you want PostgreSQL on a different machine (e.g., a Raspberry Pi or NAS) and the MCP server on your local machine:

# 1. On the server: clone the repo, configure .env, start PostgreSQL
ssh user@your-server
git clone https://github.com/DarkWolfCave/context-wolf.git
cd context-wolf
cp .env.example .env
# Edit .env, set POSTGRES_PASSWORD
docker compose up -d

# 2. On your local machine: install CLI, choose "External server"
git clone https://github.com/DarkWolfCave/context-wolf.git
cd context-wolf
bash setup.sh --install-only
cm init
# → Option [2], enter the server's IP, port 5432, matching user/password
cm setup-mcp

Security note: The compose file exposes PostgreSQL on port 5432 on all network interfaces of the server. For untrusted networks, restrict access with a firewall, bind to a specific IP (edit the ports: line: "192.168.1.37:5432:5432"), or tunnel through Tailscale/WireGuard. PostgreSQL is password-protected but raw port exposure is still a surface area.

Usage

CLI

# Save context
cm save "Implemented JWT auth with refresh tokens"

# Search
cm search "authentication"           # Current project
cm search "auth" --all               # All projects
cm smart-search "XSS prevention"     # Universal search (instructions + snippets + actions)

# Session & stats
cm session                           # Today's activity
cm stats                             # Database statistics
cm doctor                            # System health check

# TODOs
cm todo add "Fix auth bug" --priority high
cm todo start 123
cm todo done 123

# Now (cross-project sprint backlog)
cm now add "Fix auth bug" --bucket today --project myapp
cm now add "Polish settings page" --link-type todo --link-id 123   # references a TODO
cm now list
cm now move 5 week
cm now done 5

# AI Instructions
cm ai-instruction "Always use snake_case" --category style --priority should

# Infrastructure
cm infra add-host "web01" --ip 10.0.0.1 --user deploy --location extern
cm infra list-hosts

# Pinned items (pinning requires the optional GUI; CLI is read-only)
cm pinned                            # all pinned items as Markdown
cm pinned --project myapp            # global + project-scoped items
cm pinned --json                     # JSON output

Note: Pinning items is done in the optional context-wolf-ui GUI. The CLI can only list what you've pinned there. Without the GUI installed, cm pinned returns an empty list (no error).

MCP Server (Claude Code)

Automatically configured by bash setup.sh or cm setup-mcp. Exposes 44 tools: context_save, context_search, todo_add, infra_list_hosts, infra_add_host, note_save, now_add, now_list, and more.

See docs/MCP_TOOLS.md for the full list.

{
  "mcpServers": {
    "context-manager": {
      "command": "uv",
      "args": ["--directory", "/path/to/context-wolf", "run", "cm-mcp"]
    }
  }
}

Embedding Worker (Semantic Search)

cm-embed batch              # Process all unembedded entries
cm-embed stats              # Show embedding statistics

For automatic updates, set up a cron job or launchd timer (see embedding_worker/cron_embed.sh).

Privacy & Token Economy

Your data stays yours. ContextWolf runs entirely on your infrastructure:

• Local database - PostgreSQL on your machine, NAS, or Raspberry Pi. Your stored data stays on your infrastructure. (Note: Your conversation with Claude itself goes through Anthropic's API as usual - ContextWolf doesn't change that.)
• Local embeddings - Semantic search uses a lightweight ONNX model (all-MiniLM-L6-v2, ~90 MB) running on your CPU. Zero API calls for vector generation.
• On-demand retrieval - ContextWolf does NOT inject your entire database into Claude's context. MCP tools return only the relevant results for the current query (ranked by full-text search + vector similarity).

Token overhead: The 44 MCP tool definitions are deferred by default - only tool names are loaded at session start. Full schemas are fetched on-demand when Claude actually uses a tool. The actual data is only retrieved when a tool is called.

Architecture

src/
├── core/        # Database, config, backends (PostgreSQL)
├── domain/      # Business logic (actions, search, sessions)
├── features/    # Modules (snippets, TODOs, notes, infra, AI instructions)
└── cli/         # Argument parser + command handlers + setup wizard

mcp_server/      # MCP integration (stdio, 44 tools)
embedding_worker/ # ONNX-based vector embeddings (all-MiniLM-L6-v2)

Clean Architecture with 4 layers: CLI → Features → Domain → Core. Dependencies flow inward only.

Entry Points

Documentation

• docs/USER_GUIDE.md - Getting started guide
• docs/MCP_TOOLS.md - MCP tools reference (44 tools)
• docs/CLI_REFERENCE.md - Complete CLI command reference
• CHANGELOG.md - Version history

Background

ContextWolf started as a simple CLI tool to help me keep context across Claude Code sessions. No MCP, no vector search - just saving and retrieving decisions so I wouldn't repeat myself.

It grew from there, one feature at a time, based on whatever I needed next: notes, TODOs, infrastructure tracking, code snippets, semantic search. I used earlier versions in production for quite a while before several people suggested I should make it publicly available. That led to V5 - a cleanup and restructure for open source release.

That said, this is a personal project that grew organically over multiple versions. There may still be rough edges or leftover code from earlier iterations. If you find something broken or improvable, please open an issue or submit a PR. Contributions are welcome.

License

MIT - see LICENSE for details.