Cortex-MCP Documentation

Local-first bi-temporal memory graph, contradiction auditor, and token-budgeted MCP server.

1. Installation & Quick Start

Install editable with dev/gateway dependencies or run the interactive demo directly:

git clone https://github.com/codesphere-u/cortex-mcp.git
cd cortex-mcp
pip install -e ".[dev]"
cortex-mcp demo
cortex-mcp benchmark

2. Bi-Temporal Graph Model

Every TemporalFact tracks both valid time (valid_from, valid_until) and supersession pointers (superseded_by). Singular predicates automatically close superseded assertions while preserving full time-travel history via memory_time_travel.

3. Okapi BM25 & 2-Hop Context Compiler

ContextCompiler tokenizes CamelCase and snake_case identifiers, scores candidate facts and episodes with Okapi BM25, expands 2 hops across entity relations, and packs items strictly within max_tokens with 100% stale-fact suppression.

4. Contradiction Auditor

ContradictionAuditor detects negation polarity conflicts, opposing antonym pairs, predicate alias collisions, and unsuperseded singular drift. Pass auto_resolve=True or run cortex-mcp audit-contradictions --auto-resolve to supersede lower-confidence or older conflicting facts.

5. TruthGate Grounded Export

Export verified active context bundles directly into TruthGate GroundedSourceDocument JSON arrays:

cortex-mcp export-sources --query "auth_service signing" --max-tokens 1200 --output sources.json

6. MCP Transports & CLI Subcommands

Connect Claude Code or Cursor to the hosted Vercel Streamable HTTP endpoint or run locally over stdio / HTTP SSE:

claude mcp add --transport http cortex-mcp https://cortex-mcp-steel.vercel.app/mcp
cortex-mcp serve-stdio --storage .cortex/memory.json --seed-demo
cortex-mcp serve-http --host 127.0.0.1 --port 8080