title: ContextForge emoji: 🐢 colorFrom: yellow colorTo: blue sdk: gradio sdk_version: 6.26.0 python_version: '3.12' app_file: app.py pinned: false license: apache-2.0 short_description: Shared project memory for Claude and Codex agents.

ContextForge

Tenant-isolated MCP project memory for Claude and Codex agents.

ContextForge is a Python and Gradio MCP server that enables compatible AI hosts to store, search, and exchange architectural decisions, implementation notes, and structured work packets. It runs locally or on Hugging Face Spaces without requiring Docker.

Try the Hugging Face Space

Related MCP server: arcane

Live demo

• Application: https://huggingface.co/spaces/kkishor191/ContextForge

• MCP endpoint: https://kkishor191-contextforge.hf.space/gradio_api/mcp/

Example prompt:

Use ContextForge to record an architectural decision titled “Use SQLite for the MVP,” including the rationale and Codex as the source.

The hosted Space currently demonstrates the original shared-memory schema (v1). This repository contains the newer tenant-isolated schema (v2), which must be deployed and verified before tenant isolation is described as active in the live demo.

Why it exists

AI coding sessions often lose important decisions when a conversation ends or work moves between hosts. ContextForge gives Claude, Codex, and other MCP clients a shared source of durable project knowledge.

Claude / Codex
      │  Streamable HTTP MCP
      ▼
ContextForge (Gradio)
      │  trusted tenant context
      ▼
SQLite project memory

MCP tools

• record_decision, list_decisions, and search_project

• create_work_packet and get_work_packet

• record_implementation and update_record_status

• project_summary, health_check, and backup_database

Persistence modes

• Self-hosted: local SQLite, an implicit local tenant, and no API key.

• Hosted: shared SQLite with API-key authentication and tenant-scoped data.

Hosted keys use cf_live_<key-id>_<secret>. ContextForge stores only an HMAC-SHA256 digest and resolves the tenant internally. MCP tools never accept a caller-controlled tenant_id.

Run locally

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python app.py

Connect Claude or Codex to:

http://localhost:7860/gradio_api/mcp/

Then try:

Use ContextForge to record our decision to use SQLite for the MVP.
Search ContextForge for decisions about persistence and summarize them.
Create a work packet for migrating the storage adapter to PostgreSQL.

See CONNECTING.md for client and hosted-authentication examples.

Hosted configuration

Mount durable storage at /data and configure:

CONTEXTFORGE_STORAGE_MODE=hosted
CONTEXTFORGE_DB=/data/contextforge.db
CONTEXTFORGE_BACKUP_DIR=/data/backups
CONTEXTFORGE_KEY_PEPPER=<secure-random-secret>

Provision consumers with:

python admin.py create-tenant --name "Acme"
python admin.py issue-key --tenant-id "TENANT_UUID"
python admin.py revoke-key --key-id "KEY_ID"

Engineering highlights

• Native Gradio Streamable HTTP MCP server

• SQLite WAL mode, busy timeout, and bounded write retries

• Automatic schema migration and integrity-checked backups

• Structured, redacted errors with incident IDs

• Tenant-scoped record operations and revocable API keys

• Input-size and query-complexity limits

• Compatibility with a Docker-free Hugging Face Space

SQLite tenancy is application-enforced and intended for a single-instance MVP. PostgreSQL is the recommended next step for multiple replicas or sustained write concurrency.

Test

python -m unittest discover -s tests -v

The suite covers record lifecycles, migration, backups, concurrent writes, lock contention, validation, API-key authentication and revocation, MCP schema discovery, and cross-tenant access denial.

Stack

Python · Gradio · Model Context Protocol · SQLite · Hugging Face Spaces

See OPERATIONS.md for monitoring, recovery, capacity, and security guidance.