All work

Agent memory / Case study

Cortex MCP

Keep a history of what an agent knew and when.

Open the live demo
Type
Open-source engineering
Release
v1.1.0
Stack
Python 3.12 · MCP JSON-RPC 2.0 · BM25 + Graph RAG · SHA-256 Merkle
Automated tests
104

System architecture

  1. Bi-Temporal Entity-Relationship & Episode Graph (src/cortex_mcp/graph.py)
  2. Hybrid BM25 + 2-Hop Graph Context Compiler (src/cortex_mcp/compiler.py)
  3. Model Context Protocol JSON-RPC 2.0 Server (src/cortex_mcp/server.py)
Three layers from the project’s architecture blueprint

01 / Problem

Why it exists

AI coding agents suffer from context amnesia across sessions and IDEs, while static prompt files (.cursorrules, CLAUDE.md) bloat token budgets and retain stale architectural assumptions after migrations.

02 / Design

How it works

Model architectural facts as bi-temporal edges (valid_from, valid_until, superseded_by) combined with hybrid BM25 + 2-hop graph activation.

  1. Bi-Temporal Entity-Relationship & Episode Graph (src/cortex_mcp/graph.py)

    Maintains Entities, TemporalFacts, and Episodes with automatic conflict supersession, time-travel queries (as_of), and SHA-256 Merkle integrity.

  2. Hybrid BM25 + 2-Hop Graph Context Compiler (src/cortex_mcp/compiler.py)

    Scores active knowledge using code-aware BM25 + graph neighbor activation and packs the highest-utility items within max_tokens.

  3. Model Context Protocol JSON-RPC 2.0 Server (src/cortex_mcp/server.py)

    Exposes memory_record_episode, memory_upsert_fact, memory_compile_context, memory_query_entity, memory_time_travel, and memory_verify_integrity.

Bi-Temporal Fact Supersession Over Destructive Vector Overwrites
Context
Standard vector-store memory systems append new embeddings without invalidating superseded architectural decisions, causing coding agents to retrieve contradictory instructions.
Decision
Model architectural facts as bi-temporal edges (valid_from, valid_until, superseded_by) combined with hybrid BM25 + 2-hop graph activation.
Trade-offs
Requires structured (subject, predicate, object) extraction alongside free-text episodes, but guarantees 100% suppression of superseded facts while preserving point-in-time historical queries.
Verification
Verified across 104 pytest tests, bi-temporal semantic contradiction auditing, and TruthGate citation bundle export.
Security and operational constraints
  • 100% local-first execution over stdio or in-memory JSON-RPC 2.0 transport with zero external cloud telemetry.
  • Every Episode and TemporalFact carries a canonical SHA-256 content hash plus a full-graph Merkle root digest verified via memory_verify_integrity.
  • Atomic temp-file + os.replace persistence prevents corrupted memory state on abrupt process termination.
  • Singular predicate upserts automatically close the prior active fact (valid_until = now, superseded_by = new_fact.id) so active queries never return contradictory state.
  • compile_context(..., include_superseded=False) guarantees 0% stale fact leakage and never exceeds max_tokens.
  • Any tampering with stored episode or fact payloads invalidates the graph Merkle root in verify_integrity().

03 / Evidence

How to verify it

Repository-reported / Bi-Temporal Recall & Stale Suppression

100% Stale Suppression · 104 Tests

0.003 ms P50 fact upsert, semantic contradiction auditing, and TruthGate citation bundle export across 104 passing tests

Reproduce from the command line
git clone https://github.com/codesphere-u/cortex-mcp.git
cd cortex-mcp && pytest -v
python -m cortex_mcp.cli benchmark
View source on GitHubOpen the live demo
Next case study · Developer tools PatchPilot Trace a failing test to a repair you can verify.