# 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.

| Hardware Tier | Target Profile | Ingest (500 facts) | Ingest / Fact | P50 Latency | P95 Latency | P99 Latency | Resident RAM |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Low-End** | 1 vCPU, 512MB RAM, eMMC / HDD (`mmap=0`, 2MB cache) | 430.35 ms | 0.86 ms | 1.69 ms | 1.73 ms | 1.86 ms | < 12 MB |
| **Mid-Tier (Native)** | AMD Ryzen 5 Pro / ThinkPad T14, NVMe PCIe 3.0 (256MB `mmap`) | 393.55 ms | 0.78 ms | 1.71 ms | 1.78 ms | 2.47 ms | < 28 MB |
| **High-End Server** | AMD EPYC / Xeon, NVMe Gen4 (`mmap=1GB`, 64MB cache) | 185.20 ms | 0.37 ms | 0.62 ms | 0.89 ms | 1.12 ms | < 45 MB |

### Environment & Virtualization Matrix

Comparison of storage access patterns across runtime boundaries.

| Environment | Storage Layer | Sync Overhead / Batch Commit | Memory-Map Overhead | Contention Isolation |
| :--- | :--- | :--- | :--- | :--- |
| **Bare-Metal Native** | Direct NVMe NTFS / ext4 | Baseline (0.00 ms added) | Direct kernel paging | Shared-process RLock registry |
| **Virtual Machine (KVM / Hyper-V)** | virtio-scsi raw disk | + 0.12 ms per WAL flush | Near-native hypervisor MMU | Full VM isolation |
| **Container (Docker / OCI)** | overlayfs bind-mount | + 0.35 ms per fsync barrier | Host VFS mapped | Mount namespace boundary |

### Grade-Based Semantic & Structural Evaluation Matrix

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

| Level | Grade Tier | Objective / Test Case | Edge-Case Challenge | ChronoMem Result | Latency | Status |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **L0** | None | Exact keyword lookup | Zero ambiguity literal search | 1 / 1 recalled (100% precision) | 0.42 ms | **PASS** |
| **L1** | Easy | Paraphrase & technical synonym | Vocabulary shift ("RAM" vs "memory") | Target fact ranked #1 | 0.20 ms | **PASS** |
| **L2** | Normal | Single temporal invalidation | Previous config replaced by new port | Ghost fact excluded (`valid_until` cutoff) | 0.24 ms | **PASS** |
| **L3** | Medium | Multi-entity attribute association | Match attributes across target host only | Zero cross-host leakage | 0.53 ms | **PASS** |
| **L4** | Intermediate | Cross-device software isolation | Disambiguate tools on different hardware | Zero cross-device pollution | 0.45 ms | **PASS** |
| **L5** | Hard | Multi-step revision lineage ($A \to B \to C$) | Retrieve active state and full ancestry | Only $C$ returned; 3-step audit intact | 0.24 ms | **PASS** |
| **L6** | Complex | Multi-constraint packing | Category filter + entity + 60-token cap | 58 tokens packed; 0 category leaks | 0.59 ms | **PASS** |
| **L7** | Undeterministic | Conflicting assertions + trust weight | Two active sources claiming differing IPs | High-trust assertion selected; conflict flagged | 0.36 ms | **PASS** |

---

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

| Evaluation Vector | Flat-Text Memory | Dense Vector DB (pgvector/Chroma) | ChronoMem (SQLite Bi-Temporal) |
| :--- | :--- | :--- | :--- |
| **Belief Invalidation** | Manual find-and-replace | Fails (Old vectors remain in index) | Native (`superseded_by`, `valid_until`) |
| **Ghost Recall Rate** | High (String substring leaks) | High (Cosine similarity matches both) | 0.00% (Excluded at index query) |
| **Retrieval Latency** | Linear scan (> 5 ms) | 15 - 80 ms (ANN index calculation) | 0.20 - 1.80 ms (FTS5 + B-Tree) |
| **Context Window Control** | Unbounded lines | Top-$K$ fixed items (unbounded tokens) | Strict token-budget packing |
| **Operational Complexity** | None (Files) | Requires PostgreSQL / Docker daemon | None (Embedded Single File) |

---

## 4. Installation & Usage

### Installation

Requires Python 3.10+.

```bash
# 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

```python
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`)

```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:

```bash
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.