ChronoMem

Bi-temporal, graph-aware relational fact store for autonomous AI agents and Model Context Protocol (MCP) clients.

Built on embedded SQLite with Write-Ahead Logging (WAL), memory-mapped I/O (mmap), and 4-way Reciprocal Rank Fusion (RRF). Requires zero external daemons, zero Docker containers, and no background vector database processes.

1. System Architecture

ChronoMem addresses structural failure modes in stateful LLM memory architectures: temporal invalidation failure (ghost beliefs), context window inflation (token bloat), and unbounded memory daemon overhead.

                    ┌──────────────────────────────┐
                    │       User / Agent Query     │
                    └──────────────┬───────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              ▼                    ▼                    ▼
     ┌────────────────┐   ┌────────────────┐   ┌────────────────┐
     │  FTS5 BM25     │   │ Jaccard Token  │   │  Entity Graph  │
     │  Text Index    │   │ Overlap Rank   │   │  Adjacency     │
     └────────┬───────┘   └────────┬───────┘   └────────┬───────┘
              │                    │                    │
              └────────────────────┼────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────┐
                    │ 4-Way Reciprocal Rank Fusion │
                    │      + Temporal Filter       │
                    │  (valid_until IS NULL)       │
                    └──────────────┬───────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────┐
                    │ Strict Token-Budget Packing  │
                    │    (Prompt Context Window)   │
                    └──────────────────────────────┘

Core Primitives

• Bi-Temporal Tuple Representation: Every assertion maintains two independent temporal coordinates:

  • system_time: Physical ingestion timestamp (immutable audit log).

  • valid_from / valid_until: Real-world validity boundaries. An updated belief atomically terminates the prior record's validity boundary (valid_until = now()) and records the successor pointer (superseded_by = new_fact_id).

• Multi-Channel Fusion Scoring: Blends independent ranking signals using generalized Reciprocal Rank Fusion: $$RRF(d) = \sum_{c \in C} \frac{w_c}{k + \text{rank}_c(d)} \times (0.8 + 0.4 \cdot \text{trust}) \times \text{confidence}$$ where $k = 60$, with channels $C = {\text{BM25}, \text{Jaccard}, \text{EntityAlignment}}$.

• Deterministic Token Budgeting: Avoids fixed $K$-item inflation. Context selection terminates when cumulative tokens meet the exact per-query limit.

2. Benchmark Matrix

All metrics below are generated deterministically using the included reproducibility suite (python scripts/benchmark_matrix.py).

Hardware Performance Matrix

Evaluated over 500 serial fact ingestions and 100 retrieval iterations with full text matching and rank fusion.

Environment & Virtualization Matrix

Comparison of storage access patterns across runtime boundaries.

Grade-Based Semantic & Structural Evaluation Matrix

8 difficulty tiers evaluating retrieval precision, temporal reasoning, and contradiction resilience.

3. Comparative Evaluation: Vector DB vs Flat Memory vs ChronoMem

4. Installation & Usage

Installation

Requires Python 3.10+.

# Via uv
uv add chronomem

# Or clone and install editable
git clone https://github.com/eikarna/chronomem.git
cd chronomem
uv pip install -e .

Python API

from chronomem import ChronoMem

with ChronoMem("agent_memory.db") as mem:
    # 1. Ingest fact
    f1 = mem.remember("ThinkPad T14 primary interface is Wi-Fi", category="net")

    # 2. Invalidate and supersede upon state change
    f2 = mem.supersede(f1, "ThinkPad T14 primary interface switched to Ethernet", category="net")

    # 3. Query active facts with token constraint
    facts = mem.recall("ThinkPad network interface", token_budget=150, active_only=True)
    for f in facts:
        print(f"[{f['trust_score']:.1f}] {f['content']}")

    # 4. Audit lineage
    history = mem.timeline("ThinkPad T14")
    assert len(history) == 2

5. Model Context Protocol (MCP) Setup

ChronoMem implements a stdio JSON-RPC 2.0 MCP server for integration with Cursor IDE, Claude Desktop, and Hermes Agent.

Cursor IDE Configuration (.cursor/mcp.json)

{
  "mcpServers": {
    "chronomem": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/chronomem",
        "python",
        "-m",
        "chronomem.server"
      ],
      "env": {
        "CHRONOMEM_DB": "~/.chronomem/memory.db"
      }
    }
  }
}

Available MCP Tools

• chronomem_remember: Ingest assertion into bi-temporal storage with entity resolution.

• chronomem_recall: Query facts via 4-way RRF capped by token budget.

• chronomem_supersede: Atomically update an assertion, marking prior record expired.

• chronomem_forget: Soft-delete assertion preserving audit lineage.

• chronomem_timeline: Inspect belief evolution for an entity across time.

• chronomem_contradictions: Identify unresolved semantic contradictions.

6. Reproducibility

To re-run the benchmark matrix locally:

uv run python scripts/benchmark_matrix.py
uv run --with pytest pytest tests/test_chronomem.py

7. License

MIT License. Copyright (c) 2026 Nix Seymour.