Skip to main content
Glama

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: codebase-wiki

Live demo

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory and knowledge capture for AI-assisted development, enabling agents to retain decisions, bugs, and patterns across sessions and projects.
      265 PyPI
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables engineering agents to maintain persistent knowledge across sessions by storing decisions, invariants, gotchas, and rejected ideas, with staleness detection, conflict detection, full-text search, and structured context assembly.
      62
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to persist and retrieve durable project knowledge across coding sessions, capturing decisions, conventions, lessons and reusable skills through ordinary chat requests. It supports searching, editing and reviewing saved items, and promoting local notes into Git-shareable versioned knowledge alongside repository changes.
      29 npm
      3
      MIT