free-context-hub

Persistent memory and guardrails for AI coding agents — so they never start from zero again.

Every AI coding session starts with amnesia. Your agent forgets the architectural decisions you explained yesterday, the workaround you discovered last week, and the deployment rule your team agreed on last month. You re-explain, re-discover, re-enforce — over and over.

free-context-hub is a self-hosted, open-source MCP server that gives AI assistants (Claude Code, Cursor, etc.) persistent knowledge across sessions and agents — decisions, preferences, workarounds, and guardrails that survive after a conversation ends.

It also provides a web GUI for humans to review, approve, and refine AI-generated knowledge — bridging AI-to-AI and AI-to-Human collaboration.

Inspired by ContextStream. Free, local, for small teams.

What this actually is

The visible surface is memory, lessons, and guardrails for AI coding agents. The deeper arc — see ROADMAP.md for the full picture — is a five-phase research program building the MCP-served, software-substrate implementation of the Dead Light Framework (DLF): a governance methodology for hybrid human + AI organizations.

Phase 1 ─── Phase 2 ─── Phase 3 ─── Phase 4 ─── Phase 5
Memory      Eval +      Governance  Benchmark   Runtime
+ Knowledge RAG Quality Primitives  Governance  Enforcement
✅ shipped   🔄 active   🔄 active   ⏳ planned   💡 research

Phase 1 is the core feature surface most users interact with today. Phases 2 and 3 are being built in parallel on separate branches — generation-quality evaluation (Phase 2) and the coordination / governance primitives drawn from DLF (Phase 3: motions, proxies, scope, approval, dispute, multi-tier routing). Phase 4 will benchmark Phase 3 across diverse governance scenarios. Phase 5 — pre-action runtime enforcement and isolation environments for dangerous tasks — is still in literature review.

The differentiated wedge: persistent semantic memory of decisions + DLF-derived collective-decision primitives + tenant-scope isolation under one MIT roof, served via MCP. Several expansion directions are scoped for future phases — see ROADMAP.md.

Screenshots

20 pages, 70+ REST endpoints, full human-in-the-loop workflow.

Dashboard — Knowledge health, insights, activity feed

AI Chat — Markdown rendering, tool calls, conversation history

Lessons — Search, filter, import/export, feedback signals

Review Inbox — Approve AI-generated lessons, trust levels

Lesson Detail — Rich editor, comments, version history

Analytics — Retrieval trends, dead knowledge, agent activity

Documents — Upload, link, generate lessons from docs

Guardrails — Test presets, "What Would Block?" simulate mode

Tech Stack

Layer	Technology
Backend	Node.js + TypeScript, MCP protocol server
Frontend	Next.js 16, React 19, Tailwind CSS 4
Primary Database	PostgreSQL 16 + pgvector (data + embeddings)
Knowledge Graph	Neo4j 5 (optional — symbol extraction via ts-morph)
Job Queue	RabbitMQ (background workers for git ingestion, reflection)
Cache	Redis (tiered search caching)
AI Integration	MCP (Model Context Protocol) — open standard for agent tool use
Embeddings	Any OpenAI-compatible endpoint (LM Studio, Ollama, etc.)
Deployment	Docker Compose — single-node, self-hosted, zero cloud dependency

Architecture

 AI Agents (Claude Code, Cursor, etc.)
        │ MCP :3000
        ▼
 ┌─────────────────────────────────┐
 │       ContextHub Backend        │
 │  MCP Server · REST API · Chat   │
 │  Background Worker (jobs)       │
 │─────────────────────────────────│
 │        Services Layer           │
 │  lessons · guardrails · search  │
 │  git · jobs · docs · audit      │
 │─────────────────────────────────│
 │  Postgres   │ Neo4j  (optional) │
 │  + pgvector │ Redis  (optional) │
 │             │ Rabbit (optional) │
 └──────────────┬──────────────────┘
                │ REST :3001
                ▼
 ┌─────────────────────────────────┐
 │      GUI (Next.js :3002)        │
 │  20 pages · AI chat · Review    │
 │  Inbox · Analytics · Agents     │
 └─────────────────────────────────┘
                │
           Human (browser)

Core Features

1. Persistent Lessons & Knowledge

The main value proposition. Store and retrieve team knowledge that persists across sessions and agents.

add_lesson — Capture decisions, preferences, workarounds, guardrails
search_lessons — Semantic search across all stored knowledge
list_lessons — Browse with filters (type, tags, status)
update_lesson_status — Lifecycle management (draft → active → superseded → archived)
reflect — LLM-synthesized answers from multiple lessons (optional, requires chat model)

Example workflow:

Agent A (Monday):   add_lesson("We use JWT not sessions — legal requires stateless auth")
Agent B (Thursday): search_lessons("authentication approach") → gets the decision instantly
Agent C (Next month): Doesn't waste time debating sessions vs JWT

2. Guardrails

Prevent repeated mistakes by enforcing team rules before risky actions.

check_guardrails — Pre-action safety verification (git push, deploy, migrations)
Guardrails are derived from lessons with lesson_type: "guardrail"
Returns pass/fail + prompt for user confirmation when blocked

3. Session Bootstrap

Quick onboarding for new agent sessions.

get_context — Bootstrap with project state + suggested next calls
get_project_summary — Full project briefing in one read
help — Tool discovery and sample workflows

4. Human-in-the-Loop GUI

A full web dashboard where humans review, approve, and refine AI-generated knowledge.

Review Inbox — Batch approve/reject AI-generated lessons with trust levels
Rich Content Editor — Markdown toolbar, live preview, keyboard shortcuts (Ctrl+B/I)
AI Editor — Clarify, simplify, expand lessons with diff view (accept/reject)
Comments & Feedback — Threaded comments, thumbs up/down, bookmarks
Activity & Analytics — Timeline, retrieval trends, dead knowledge detection
Documents — Upload reference docs, generate lessons from them
Global Search — Cmd+K across all knowledge

5. Access Control & Agent Audit

Secure multi-agent environments with role-based access and full audit trails.

API Keys with Roles — Admin, editor, viewer permissions via SHA-256 hashed keys
Agent Audit Trail — Unified timeline of all agent actions (guardrail checks, lessons created)
Custom Lesson Types — Define project-specific types beyond the defaults
Feature Toggles — Enable/disable capabilities per project

6. Code Search (Supplementary)

Semantic code search assists agents in finding relevant code. Supplementary — agents already have built-in Grep/Glob.

search_code_tiered — Multi-tier search with auto-selected profiles:
- code-search: ripgrep → symbol → FTS → semantic
- relationship: convention paths → KG imports → filtered ripgrep
- semantic-first: vector similarity → FTS (for docs/scripts)

7. Git Intelligence (Supplementary)

Auto-collect insights from commit history.

ingest_git_history / suggest_lessons_from_commits — Draft lessons from git
analyze_commit_impact — Commit impact over symbol/lesson graph

8. Knowledge Graph (Optional)

Symbol-level code structure for advanced queries. Requires Neo4j.

search_symbols / get_symbol_neighbors / trace_dependency_path
get_lesson_impact — Which code does a lesson affect?

Quickstart

Prerequisites

Node.js 20+ and npm
Docker (for PostgreSQL + pgvector)
Embeddings server — LM Studio or any OpenAI-compatible endpoint

Setup

# 1. Clone and install
git clone https://github.com/your-username/free-context-hub.git
cd free-context-hub
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL and EMBEDDINGS_BASE_URL

# 3. Start infrastructure
docker compose up -d

# 4. Launch the backend (MCP + API)
npm run dev

# 5. Verify everything works
npm run smoke-test

# 6. (Optional) Launch the GUI
cd gui && npm install && npm run dev

Connect Your AI Tool

Add the MCP server URL in your tool's settings:

http://localhost:3000/mcp

Service	URL
MCP Server	`http://localhost:3000/mcp`
REST API	`http://localhost:3001`
Web GUI	`http://localhost:3002`

Detailed setup: docs/QUICKSTART.md

Self-Hosted Models

ContextHub uses OpenAI-compatible APIs. Run locally with LM Studio or any compatible server.

Recommended Combo (benchmarked)

We tested 8 embedding models and 8 reranker models (embedding/reranker benchmark), plus 6 distillation models (distillation benchmark). Best combo:

Role	Model	Config
Embeddings	`qwen3-embedding-0.6b`	`EMBEDDINGS_DIM=1024` — best accuracy (18/18 pass, avg 0.652)
Reranker	`qwen3-4b-instruct-ranker`	`RERANK_MODEL=qwen3-4b-instruct-ranker` — +9% accuracy at 180 lessons
Distillation	`ibm/granite-4-h-tiny`	`DISTILLATION_ENABLED=true` — non-reasoning, ~100K context; reflect, compress, summarize

Alternative Models

Embedding (8 tested, lesson search accuracy):

Model	Dims	Pass Rate	Avg Score	Notes
qwen3-embedding-0.6b	1024	18/18	0.652	Recommended
bge-m3	1024	18/18	0.575	Fast, solid all-rounder
mxbai-embed-large-v1	1024	17/18	0.648	Close but 1 failure

Reranker (8 tested, 180 lessons / 33 queries):

Model	Type	Pass Rate	Latency	Notes
qwen3-4b-instruct-ranker	generative	85%	1.8s	Recommended — no thinking overhead
qwen.qwen3-reranker-4b	generative	85%	1.9s	Thinking mode, same accuracy
rank_zephyr_7b	generative	82%	~2s	RankGPT format
(no rerank)	—	76%	99ms	Baseline

Distillation (6 tested — chat model for reflect/compress/summarize; full benchmark):

Model	Reasoning	Speed	Notes
ibm/granite-4-h-tiny	No	in-stack `add_lesson` ~5.6s	Recommended — 0 reasoning tokens, ~100K context (max 1M)
microsoft/phi-4	No	in-stack `add_lesson` ~3.7s	Faster, but only a 16K context window
mistral-nemo-instruct-2407	No	non-reasoning	Viable alternative, 128K context
qwen3.5-9b	Yes	—	Reasoning cannot be disabled via the API
deepseek-r1-distill-qwen-32b	Yes	~5 tok/s	Non-thinking is possible (32B) but too slow
nvidia/nemotron-3-nano	Yes	~25-35s/call	Previous default — chain-of-thought overhead

Note: Code search uses ripgrep/FTS (deterministic), not embeddings. Cross-encoder rerankers (bge-reranker, gte-reranker) don't work via LM Studio — they need a dedicated /v1/rerank API.

Roadmap

For the strategic five-phase arc (Memory → Eval → Governance → Benchmark → Runtime Enforcement) and its DLF lineage, see ROADMAP.md. The list below is the sprint-level history mapped to the strategic phases.

Completed:

In Progress:

Phase 16: Production-Ready RAG with Generation-Quality Evaluation (separate branch)
- 152-row gen-eval dataset (127 retrieval queries + 25 hand-curated edge cases)
- Ragas judge sidecar (Python / FastAPI) running google/gemma-4-26b-a4b-it
- Metrics: faithfulness, answer_relevancy, context_precision, context_recall, refusal_correctness, groundedness_self_eval
- Threshold gates in WARN mode until 2 weeks of baseline variance data, then flip to BLOCK
Phase 17: Anti-Hallucination Experiments (separate branch)
- Citation-forced prompt templates, selective abstention
- Chain-of-Verification synthesizer
- groundedness_self_eval metric for model-side grounding check

Planned (no detailed design yet):

Phase 18 — Governance Benchmark Suite
- Catalog of governance scenarios across org topologies (flat / hierarchical / federated), conflict patterns (collaborative / adversarial / byzantine), and human + AI mixes
- Per-scenario success metrics: right outcome, right number of steps, right principals, auditability intact
Phase 19 — Runtime Enforcement & Isolation
- Pre-action policy engine that blocks agent behavior before it occurs
- Isolated environments for experimental / dangerous tasks
- Open design questions: policy DSL (DLF-native vs OPA Rego / Cedar), enforcement location (gateway / SDK / OS sandbox), cryptographic identity (DIDs vs scoped API keys), isolation primitive (container / VM / WASM / seccomp)

Intentionally Dropped:

~~Multi-Agent Passive Collection~~ — Parsing agent conversations costs tokens and captures noise. add_lesson captures verified conclusions explicitly.
~~Session History Sharing~~ — Transcripts are 50k-200k tokens. The value is conclusions, not the journey.
~~IDE Extension~~ — Agents use MCP (done). Humans use the web GUI — works in any browser including VS Code's built-in browser.

Project Stats

Metric	Count
MCP Tools	45+
REST Endpoints	105+
GUI Pages	23
Database Migrations	63
Unit Tests	843
E2E Tests	300 (api 128 + gui 52 + smoke 111 + agent 9)
Sprint Phases	15 complete + DEFERRED-029 · Phase 16/17 active on separate branches
Strategic Arc	Phase 1 shipped · Phase 2 + Phase 3 in progress · Phase 4 + Phase 5 planned (ROADMAP.md)

Contributing

Contributions are welcome! This is a solo project that grew into something useful — fresh eyes and ideas are appreciated.

Fork the repo
Create a feature branch (git checkout -b feature/my-feature)
Make your changes
Run npm run smoke-test to verify
Submit a pull request

Please open an issue first for large changes so we can discuss the approach.

Troubleshooting

Unauthorized: invalid workspace_token: Set MCP_AUTH_ENABLED=false in .env or provide the correct token.
dimension mismatch: Ensure EMBEDDINGS_DIM=1024 matches your model's output.
401 Unauthorized (LM Studio): Check EMBEDDINGS_API_KEY in your .env.

License

MIT — see LICENSE for details.

Roadmap | Whitepaper | Quickstart Guide | Knowledge Exchange Reference

Name		Name	Last commit message	Last commit date
.claude/commands		.claude/commands
.cursor		.cursor
.github/workflows		.github/workflows
agentic-workflow		agentic-workflow
config/taxonomy-profiles		config/taxonomy-profiles
corpus		corpus
docs		docs
gui		gui
migrations		migrations
packages/mcp-client		packages/mcp-client
qc		qc
scripts		scripts
services		services
src		src
test-data		test-data
test/e2e		test/e2e
.dockerignore		.dockerignore
.env.baseline		.env.baseline
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
WHITEPAPER.md		WHITEPAPER.md
docker-compose.auth-test.yml		docker-compose.auth-test.yml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.hardened-test.yml		docker-compose.hardened-test.yml
docker-compose.yml		docker-compose.yml
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation