CortexMemory

Bi-Temporal, 4-Tier Hybrid Cognitive Memory Engine for Autonomous Coding Agents

CortexMemory provides external cognitive memory for AI coding assistants via the Model Context Protocol (MCP). By decoupling active working context from long-term memory, it maintains a lean, stationary context window ($O(1)$) that cuts token consumption by ~82%, eliminates compaction amnesia, and prevents repetitive debugging loops.

The engine runs 100% locally on your machine using Docker (PostgreSQL 16 + Neo4j 5.26) and local vector embeddings.

Architecture Overview

CortexMemory separates memory into 4 distinct tiers coordinated across two asynchronous pathways:

The Dual Pathways

1. The Hot Path (Sub-Second Interaction):

   • Every tool call, error, and diff is logged non-blockingly to PostgreSQL (Tier 2) in < 5ms.

   • When the agent queries memory, the Cognitive Memory Router blends active scratchpad state (Tier 1), dense vector retrieval (Tier 3), and bi-temporal graph traversals (Tier 4) via Reciprocal Rank Fusion (RRF): $$RRF(d) = \sum_{m \in {\text{vector}, \text{graph}, \text{episodic}}} \frac{w_m}{k + \text{rank}_m(d)}$$

   • A Token Budgeter packs the top ranked facts into a lean Markdown injection capped at 2,500 tokens.

2. The Sleep-Cycle Consolidation Path (Background Reflection):

   • An AFTER INSERT trigger on PostgreSQL fires pg_notify('new_episode_channel').

   • The background daemon wakes reactively (no polling) and claims unconsolidated batches using SELECT ... FOR UPDATE SKIP LOCKED.

   • It distills raw events through a lightweight reflection model (Claude 3.5 Haiku, Gemini Flash, or local Ollama) into 4 atomic operations:

     • ADD: Inserts a new entity or dependency edge (valid_from = now(), valid_to = null).

     • UPDATE: Refreshes properties or bumps confidence scores.

     • DELETE: Sets valid_to = now() on superseded relationships (soft invalidation).

     • NOOP: Discards transient noise (e.g. ls, exploratory file reads).

   • Updates are committed to Neo4j, and episodes are marked consolidated = true.

Related MCP server: Agent Memory Bridge

🧠 The Memory Hierarchy & Engine Philosophy

Why Flat Context & Naive Vector RAG Fail

The 4-Tier Memory Hierarchy (Computer Architecture Analogy)

CortexMemory maps cognitive memory to computer storage tiers (Registers $\rightarrow$ SSD WAL $\rightarrow$ Inverted Index $\rightarrow$ Relational Topology):

┌─────────────────────────────────────────────────────────────────────────────┐
│  Tier 1: Working Memory (RAM / L1 Cache)                                    │
│  - Engine: In-Memory / Python dictionary (Strict 4,000 token ceiling)       │
│  - Role: Active goal, current debugging hypothesis, transient scratchpad   │
│  - Benefit: Sub-millisecond prompt focus; prevents task drift               │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ (Async Log & Action Stream)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Tier 2: Episodic Store (Write-Ahead Log / SSD)                             │
│  - Engine: PostgreSQL 16 (JSONB, GIN Indexing, SHA-256 Hashes)              │
│  - Role: Append-only audit trail of every tool execution, diff, and output  │
│  - Benefit: Lossless auditability; instant repetitive error detection via   │
│             SHA-256 hash match; zero-polling pg_notify triggers             │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ (Background Sleep-Cycle Consolidation)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Tier 3: Semantic Store (Fast Inverted Search Index)                        │
│  - Engine: Neo4j Native Lucene Vector Index (1536-dim Cosine Similarity)    │
│  - Role: Dense vector embeddings of entities, patterns, and decisions       │
│  - Benefit: Conceptual discovery when exact symbol names are unknown        │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ (Unified in Neo4j)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Tier 4: Knowledge Graph (Bi-Temporal Relational Topology)                  │
│  - Engine: Neo4j Bi-Temporal Property Graph                                 │
│  - Role: Code entities and edges with [valid_from, valid_to] intervals      │
│  - Benefit: Multi-hop dependency traversal; deterministic temporal          │
│             disambiguation (valid_to IS NULL = active, non-null = obsolete) │
└─────────────────────────────────────────────────────────────────────────────┘

Quantitative Benchmark: Flat Context vs. CortexMemory

Measured over a 50-turn refactoring task:

Key Use Cases

1. Halting Repetitive Debugging Loops

• Scenario: An agent encounters an environment or test error, attempts a fix that fails, and later repeats the exact same attempt because previous command outputs rolled off context.

• Cortex Action: Every error is indexed with a canonical SHA-256 hash in Tier 2. When the same failure repeats, Cortex flags repetitive_loop_detected: true with the occurrence count, instructing the agent to change approach immediately.

2. Temporal Disambiguation During Refactors

• Scenario: A project migrates from REST to tRPC. An agent reading older commits or documentation attempts to generate obsolete REST endpoints.

• Cortex Action: Consolidation marks obsolete relationships with valid_to = datetime(). Cypher queries filter WHERE valid_to IS NULL, ensuring only currently active architecture conventions are supplied to the prompt.

Quickstart & Setup

1. Launch Infrastructure

Starts PostgreSQL 16 and Neo4j 5.26 with pre-configured schemas and APOC plugins:

docker compose -f docker/docker-compose.yml up -d

• PostgreSQL: localhost:5432 (user: cortex, db: cortex_memory)

• Neo4j Browser: http://localhost:7474 (user: neo4j, pass: cortex_secure_password)

2. Install & Verify

uv sync
uv run pytest

(Runs the 42 unit and integration tests across storage tiers, hashing, RRF, and FastMCP tools).

Agent Integration (FastMCP)

CortexMemory implements the Model Context Protocol (MCP), connecting directly to Claude Code, Cursor, Windsurf, and Antigravity.

Client Configuration (~/.claude.json or cursor.json)

{
  "mcpServers": {
    "cortex-memory": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/supreme/Dev/cortex-memory",
        "run",
        "python",
        "-m",
        "cortex.mcp.server"
      ]
    }
  }
}

Available MCP Tools

Example Usage

1. Ingesting Events & Detecting Loops

# Agent logs a test failure
response = await cortex_record_event(
    session_id="session_01",
    turn_index=12,
    event_type="test_failure",
    payload={"stderr": "AssertionError: 401 != 200 at auth.test.ts:45"},
    outcome_status="FAILED",
    target_entity="src/auth/jwt.ts"
)

# Output:
# {
#   "event_id": "c71a39...",
#   "content_hash": "8ea6c75...",
#   "repetitive_loop_detected": true,
#   "occurrence_count": 2
# }

2. Querying Memory for Synthesized Context

# Agent queries relevant architectural facts before editing
context = await cortex_query_memory(
    query="How is authentication validated in API routes?",
    target_entity="src/api/routes.ts",
    max_tokens=1500
)

# Injected Context:
# ### Active Working Scratchpad
# **Active Goal:** Migrate from REST to tRPC
# 
# ### Graph Dependencies
# - src/auth/session.ts (depth 1) [USES_PROTOCOL: tRPC]
# - src/models/user.ts (depth 2)

License

Apache 2.0