Context Library

Context Library

[](https://github.com/onideus/context-library/actions/workflows/ci.yml) [](https://github.com/onideus/context-library/actions/workflows/image.yml) [](https://github.com/onideus/context-library/releases/latest) [](LICENSE)

A personal MCP server that provides persistent operational context, task management, knowledge capture, artifact tracking, and semantic search across AI assistant sessions. Model-agnostic, Docker-ready, designed for single-user cognitive infrastructure.

What It Does

AI assistants lose all context between conversations. Context Library solves this by providing MCP tools that any compatible assistant can use to store and retrieve operational state, track tasks, capture permanent knowledge, and search across accumulated history.

The server name is configurable via the SERVER_NAME environment variable (default: context-library). Name it whatever fits your mental model.

Deployment Tiers

Context Library is designed to be deployed incrementally. Each tier adds functionality on top of the previous one, using Docker Compose file stacking.

Tier 1: Core (Handoffs Only)

The simplest deployment. Stores and retrieves operational context as append-only JSON files. No database required.

docker compose up -d

Available tools: store_handoff, get_latest_handoff, patch_handoff, list_handoffs, get_handoff

> Handoff files are retained indefinitely by default (RETENTION_COUNT=0). For long-lived deployments, set RETENTION_COUNT to a positive number (e.g., 5000) to cap disk growth — older handoffs are pruned along with their search-index entries. The tradeoff: higher retention keeps more history searchable; lower retention keeps the disk footprint tight. Compaction (automatic after each store) reduces per-file size either way.

Tier 2: + PostgreSQL (Tasks + Knowledge + Artifacts + Full-Text Search)

Adds structured task management, permanent knowledge capture, generated-output tracking, and full-text search. Requires PostgreSQL 16 with pgvector.

docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d

Additional tools: create_task, get_task, list_tasks, update_task, search_tasks, create_note, get_note, list_notes, search_notes, update_note, delete_note, store_artifact, get_artifact, list_artifacts, search_artifacts, update_artifact

Tier 3: + Embeddings (Semantic Search)

Adds vector-based semantic search across all stored content using a Text Embeddings Inference (TEI) server. Use the --profile flag to select GPU or CPU runtime.

GPU (desktop with NVIDIA GPU):

docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.embeddings.yml --profile embeddings-gpu up -d

CPU (NAS or any machine without GPU):

docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.embeddings.yml --profile embeddings-cpu up -d

With no --profile flag, neither TEI service starts — the application degrades gracefully (semantic search falls back to FTS).

Additional tools: search_context, reindex

The TEI server can run on a separate machine — just point EMBEDDING_URL to its address. This is the recommended setup if your main server doesn't have a GPU.

Optional: Cross-Encoder Reranker

For improved retrieval precision, an optional cross-encoder reranker rescores candidates after RRF fusion. It runs as a second TEI instance:

# Add to your compose command:
--profile reranker-gpu   # or reranker-cpu

When the reranker is not configured or unreachable, search_context falls back to RRF-only ordering. Set RERANKER_URL in your .env to enable it.

Embedding Server Platform Options

| Platform | Profile / Method | GPU Acceleration | |---|---|---| | Linux/Windows (NVIDIA GPU) | --profile embeddings-gpu | CUDA (compute capability 7.5+) | | Linux/Windows (no GPU) | --profile embeddings-cpu | None (CPU only, x86_64) | | Apple Silicon / ARM servers (Docker) | --profile embeddings-arm64 | None (CPU only, native ARM) | | macOS Apple Silicon (native) | Homebrew: text-embeddings-inference | Metal (via native binary only) |

> Apple Silicon note: macOS does not support GPU passthrough into Docker containers. Running TEI in Docker on M-series Macs will be CPU-bound and slow. For CPU-only Docker deployment on Apple Silicon, use --profile embeddings-arm64. For Metal GPU acceleration, install TEI natively via Homebrew and run it outside of Docker: > > ``bash > brew tap huggingface/tap > brew install huggingface/tap/text-embeddings-inference > text-embeddings-router --model-id nomic-ai/nomic-embed-text-v2-moe --port 8090 > ` > > Then set EMBEDDINGURL=http://host.docker.internal:8090 (Docker) or EMBEDDINGURL=http://localhost:8090` (local dev) so Context Library can reach it.

Tier 4: + Entity Extraction (Knowledge Graph)

Adds background extraction of entity triples (subject → relation → object) from handoffs and notes into a queryable knowledge graph. Extraction runs against an external LLM provider — either a local Ollama instance or an Anthropic/OpenAI-compatible API.

docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.entities.yml up -d

Extraction is disabled by default (ENTITY_EXTRACTION_ENABLED=false) and is fully fire-and-forget: if the provider is unreachable, handoff and note writes still succeed and a warning is logged. Ollama itself is not managed by Compose — point OLLAMA_BASE_URL at wherever it runs.

Additional tools: extract_entities, run_extraction, compare_extractions, list_extraction_runs, browse_entities, entity_relations

Architecture

• Server: Hono 4.x + StreamableHTTP MCP transport (Node.js 22, TypeScript)
• Storage (Tier 1): Append-only JSON files in ./data/handoffs/
• Database (Tier 2): PostgreSQL 16 with pgvector extension
• Content primitives: Handoffs (ephemeral session state), Tasks (lifecycle-managed action items), Notes (permanent knowledge — decisions, patterns, insights), Artifacts (generated outputs with lifecycle state and execution ordering)
• Embeddings (Tier 3): Text Embeddings Inference with nomic-embed-text-v2-moe (768 dims), optional cross-encoder reranker
• Search: Hybrid retrieval (vector + FTS with RRF fusion), optional cross-encoder reranking, entity-aware context envelopes, search alias expansion, date-range filtering
• Auth: Handled externally by mcp-auth-proxy — the server itself is unauthenticated and trusts its network boundary

Each component degrades gracefully when unavailable. If Postgres is down, handoffs still work. If the embedding server is unreachable, task, note, and artifact search still works via full-text search; failed embeddings are queued for automatic retry when TEI comes back.

The Autonomous Pipeline Pattern

The four content primitives (handoffs, tasks, notes, artifacts) are enough substrate to run an autonomous build pipeline against your own repositories. A planning session stores ready artifacts. A separate interceptor process polls list_artifacts, claims work by transitioning status to executing, runs the artifact content as a prompt against a target repo, opens a PR, gates the merge behind adversarial review + CI, and writes a digest note back to Context Library.

The reference implementation is private. What is documented here is the pattern — the contracts between planner, artifact store, interceptor, and review gate — so you can build your own on top of a Tier 2+ deployment. See [docs/pipeline/](docs/pipeline/README.md) for the full write-up: lifecycle rules, governance model, replication spec, and worked example.

MCP Tools

| Tool | Tier | Description | |---|---|---| | store_handoff | Core | Full-state capture at session boundaries (append-only) | | get_latest_handoff | Core | Retrieve most recent handoff with pre-computed fields | | patch_handoff | Core | Partial update with merge semantics | | list_handoffs | Core | Browse historical handoffs by date with metadata | | get_handoff | Core | Retrieve a specific historical handoff by filename | | create_task | Postgres | Create task with scope, priority, tags, dates | | get_task | Postgres | Retrieve task by UUID | | list_tasks | Postgres | Paginated filtering with status, scope, priority, tags | | update_task | Postgres | Field updates + lifecycle actions (complete/cancel/defer/reopen) | | search_tasks | Postgres | Full-text search with PostgreSQL FTS | | create_note | Postgres | Capture permanent knowledge (decisions, patterns, insights) | | get_note | Postgres | Retrieve note by UUID | | list_notes | Postgres | Browse notes with scope, domain, and tag filters | | search_notes | Postgres | Full-text search across note titles and content | | update_note | Postgres | Update note fields; re-embeds on content change | | delete_note | Postgres | Permanently delete a note and its embedding | | store_artifact | Postgres | Capture a generated output (CC prompt, research, template) with lifecycle state | | get_artifact | Postgres | Retrieve artifact by UUID (full content + pointer + metadata) | | list_artifacts | Postgres | Browse artifacts with type, status, scope, and tag filters; execution_order-aware sort | | search_artifacts | Postgres | Full-text search across artifact titles and content | | update_artifact | Postgres | Update artifact fields; enforces status transitions; re-embeds on content change | | search_context | Embeddings | Hybrid semantic search (vector + FTS with RRF fusion) across all content types | | reindex | Embeddings | Rebuild semantic search index for handoffs, tasks, notes, and artifacts | | extract_entities | Entities | Trigger entity extraction on a single content item | | run_extraction | Entities | Batch-extract entities from multiple content items | | compare_extractions | Entities | Compare two extraction runs (e.g., different providers or models) | | list_extraction_runs | Entities | List recent entity extraction runs with stats | | browse_entities | Entities | Browse the extracted entity graph with type and name filters | | entity_relations | Entities | Retrieve the relation graph for a specific entity |

The server also registers three MCP prompts as workflow entry points: session_start (load handoff state at conversation start), architect (load prior design decisions before architecture discussions), and plan (load task and artifact state before planning).

Health Checks

The server exposes two health endpoints:

• GET /health — Basic liveness check. Returns server status, version, and uptime.
• GET /health/ready — Readiness check. Verifies the data directory is writable. Returns "ok" (HTTP 200) or "degraded" (HTTP 503) accordingly.

Both return JSON. Use /health for uptime monitoring and /health/ready after deployment to confirm the server can write data.

curl http://localhost:3100/health
# {"status":"ok","version":"0.10.0","uptime":42}

curl http://localhost:3100/health/ready
# {"status":"ok","writable":true,"uptime":42}

Quick Start

Prerequisites

• Docker and Docker Compose
• For local development without Docker: Node.js 22+
• For external access: an OIDC provider (Auth0, Google, etc.) and a reverse proxy or tunnel
• For Tier 3 embeddings: an NVIDIA GPU (Linux/Windows), or Apple Silicon Mac with Homebrew, or any CPU (slower)

Setup

git clone https://github.com/onideus/context-library.git
cd context-library
cp .env.example .env
# Edit .env with your configuration

> Data directory ownership: The container runs as appuser (UID 999). If you're migrating data from an existing deployment or running on a NAS, ensure the data/ directory is owned by the correct UID: > > ``bash > sudo chown -R 999:999 ./data > ` > > Without this, the server will fail with EACCES: permission denied when writing handoff files. The proxy-data/ and proxy-certs/ directories (used by mcp-auth-proxy`) do not need this — the proxy runs as root.

Local Development

npm install
npm run dev          # Start with hot reload (tsx watch)
npm test             # Run test suite
npm run build        # TypeScript compile

The server starts on http://localhost:3100 by default. The MCP endpoint is at http://localhost:3100/mcp. Verify it's running:

curl http://localhost:3100/health

Connecting MCP Clients

Once Context Library is running (either via npm run dev or Docker), you can connect any MCP-compatible client. The server uses Streamable HTTP transport on a single endpoint: http://localhost:3100/mcp.

Roo Code (VS Code)

Roo Code is the most common local setup. Open your MCP settings (click the MCP icon in the Roo Code panel, then Edit Global MCP or Edit Project MCP) and add:

{
  "mcpServers": {
    "context-library": {
      "type": "streamable-http",
      "url": "http://localhost:3100/mcp"
    }
  }
}

For project-level configuration, create .roo/mcp.json in your project root with the same content. Project-level configs override global settings and can be committed to version control so your whole team shares the same MCP setup.

Save the file and Context Library should appear in the MCP servers list with a connected status. Roo Code will discover all available tools automatically.

Claude Code (Terminal)

claude mcp add context-library --transport http http://localhost:3100/mcp

This registers the server globally. Claude Code will connect on next launch.

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Windows (Store): %LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude\claude_desktop_config.json

Claude Desktop does not natively support remote HTTP MCP servers. Use mcp-remote as a stdio bridge:

{
  "mcpServers": {
    "context-library": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3100/mcp"]
    }
  }
}

Restart Claude Desktop after saving.

Claude.ai (Hosted)

Claude.ai requires the server to be publicly accessible with OAuth authentication. See [External Access with Auth Proxy](#external-access-with-auth-proxy) below.

Other MCP Clients

Any client that supports Streamable HTTP transport can connect to http://localhost:3100/mcp. This includes VS Code with GitHub Copilot, Cursor, Windsurf, Continue, and others. Consult your client's documentation for the MCP server configuration format — typically you need to specify the URL and transport type (streamable-http or streamableHttp depending on the client).

Verifying the Connection

After connecting, ask your AI assistant to call get_latest_handoff. If it returns a handoff (or an empty-state response on first use), the connection is working. You can also hit the health endpoint directly:

curl http://localhost:3100/health
# {"status":"ok","version":"0.10.0","uptime":42}

External Access with Auth Proxy

To expose Context Library to the internet (required for Claude.ai and other hosted MCP clients), use the auth compose overlay. It bundles mcp-auth-proxy (OAuth 2.1 gateway) and a Cloudflare Tunnel connector so the full ingress chain is managed as a single stack:

Internet → cloudflared → mcp-auth-proxy:443 → context-library:3100

Auth Proxy Setup

docker compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.auth.yml \
  up -d

Fo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: onideus
• Source: onideus/context-library
• License: MIT

Install and usage instructions live in the source repository linked above.