genome

# GENOME

**Open memory for AI agents. Same answer accuracy as Mem0 - but ~1,000× cheaper to store, runs fully offline, and keeps an auditable record.**

[![tests](https://github.com/NORTHTEKDevs/genome/actions/workflows/tests.yml/badge.svg)](https://github.com/NORTHTEKDevs/genome/actions/workflows/tests.yml)
[![install canary](https://github.com/NORTHTEKDevs/genome/actions/workflows/install-canary.yml/badge.svg)](https://github.com/NORTHTEKDevs/genome/actions/workflows/install-canary.yml)
[![PyPI](https://img.shields.io/pypi/v/genome-memory)](https://pypi.org/project/genome-memory/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
![Python 3.11-3.14](https://img.shields.io/badge/python-3.11--3.14-blue)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21987934.svg)](https://doi.org/10.5281/zenodo.21987934)

**Papers:** [Do Agents Need an LLM to Remember?](https://doi.org/10.5281/zenodo.21987934) (the core evaluation, 2026) and [What Does Each Memory Feature Buy?](https://doi.org/10.5281/zenodo.22002654) (a measured audit of all five optional features, wins and failures alike, 2026). PDFs in [`papers/`](./papers/); result tables in [`benchmarks/AUDIT-RESULTS.md`](./benchmarks/AUDIT-RESULTS.md).

Most agent-memory tools (like Mem0) call an LLM on **every message** to decide what to
remember. That's the slow, expensive part - and GENOME's bet is that you don't need it.
GENOME just embeds each message locally: no LLM, no API, no network in the write path.

Benchmarked honestly on public datasets (LoCoMo, LongMemEval), GENOME **answers just as
accurately as Mem0** - while storing memories for a tiny fraction of the cost and running
completely offline.

> **Honest up front:** on answer accuracy, GENOME *ties* Mem0 - we do **not** claim to beat
> it there (six independent benchmark configurations confirm parity, none significant in
> either direction). The advantage is cost, speed, offline operation, and a
> temporal/auditable record Mem0 can't produce.

## See it work

![GENOME storing a two-year timeline and answering point-in-time questions](docs/demo.gif)

Every frame is real output from [`examples/demo_timeline.py`](./examples/demo_timeline.py),
captured by [`tools/render_demo_gif.py`](./tools/render_demo_gif.py). Run it yourself,
no API key required:

```bash
python examples/demo_timeline.py
```

The interesting part is step 3. The same question gets three different correct answers
depending on *when* you ask about, because the store keeps when each fact became true
rather than overwriting it:

| Question | Answer |
|---|---|
| What was Priya's city in May 2023? | Boston [Mar 2023 - Jan 2024] |
| What was Priya's city in March 2024? | Seattle [Jan 2024 - Feb 2025] |
| What is Priya's city now? | Austin [Feb 2025 - present] |

The "thinking about maybe moving to Denver, nothing decided" turn is stored but never
becomes an answer: it is a plan, not a durable fact.

## How it works

The write path is deliberately dumb and cheap. All the intelligence happens at read time,
when there is a query to focus it.

```mermaid
flowchart LR
    M["incoming message"] --> E["local embedder<br/>all-MiniLM-L6-v2"]
    E --> S[("local store<br/>SQLite or Postgres")]
    M -. "optional, opt-in" .-> B["belief extraction<br/>(the only LLM call)"]
    B --> K[("bi-temporal<br/>fact log")]

    Q["query"] --> R["exact cosine search<br/>over this tenant's rows"]
    S --> R
    R --> RR["optional cross-encoder<br/>rerank"]
    RR --> A["context for the agent"]
    Q --> PIT["as-of resolution<br/>facts_valid_at(entity, T)"]
    K --> PIT
    PIT --> A

    style E fill:#0A84FF,color:#fff
    style S fill:#1c2530,color:#fff
    style K fill:#1c2530,color:#fff
    style B fill:#3a3a3a,color:#fff
```

Write: embed locally, store. About 10 ms, zero LLM calls, zero network calls. The
embedding is deterministic -- the same text always yields the same vector, with no
sampled extraction step deciding what matters -- so what gets stored is a function
of the input, and replaying a journal reproduces that store exactly. (Ids and
timestamps are stamped per write, so two independent ingests of the same
conversation agree on content and vectors, not on record ids.)

Read: exact cosine search within the tenant's scope (no ANN index to build or update),
with an optional local cross-encoder reranker.

Bi-temporal layer (opt-in): records each fact at its **domain time**, the moment it became
true in the world, not the moment it was ingested. That is what makes point-in-time
questions answerable even when facts arrive out of order.

### Why the record can be re-derived

```mermaid
flowchart TB
    subgraph LLM["LLM-extraction memory"]
        A1["message"] --> A2["LLM decides what matters<br/>(sampled, non-deterministic)"]
        A2 --> A3[("store")]
        A3 --> A4["replaying the same input<br/>can produce a different store"]
    end
    subgraph GEN["GENOME"]
        B1["message"] --> B2["local embedding<br/>(deterministic)"]
        B2 --> B3[("store")]
        B3 --> B4["replaying the same input<br/>reproduces the same store"]
    end
    style A4 fill:#5c1f1f,color:#fff
    style B4 fill:#1f4d33,color:#fff
```

A record that cannot be re-derived is difficult to audit. That property, not accuracy, is
the actual argument for this design.

## Don't believe it? Prove it yourself

The **cost, speed, and offline** claims need no API key - measure them on *your* machine in 60 seconds:

```bash
git clone https://github.com/NORTHTEKDevs/genome && cd genome
pip install -e . && python -m genome.verify
```

The **first** run downloads the local embedding model (~90 MB, one time) before printing
anything, so expect 30-120 seconds of apparent silence on a cold machine. Every run after
that is instant.

It writes memories with your **outbound network physically blocked** and prints a live
pass/fail receipt - 0 network calls, 0 LLM calls, single-digit-ms writes, retrieval that works:

```
  [PASS] Air-gapped write path: wrote 200 memories with every outbound socket blocked -> 0 network attempts, 0 LLM calls
  [PASS] Write latency: 7.1 ms/message  (Mem0's measured write path: ~2,055 ms + 1 LLM call/message)
  [PASS] Retrieval works: top hit score 0.598
```

That receipt covers the cost/speed/offline story only. The **accuracy-parity with Mem0** claim
is a separate, larger check that needs an LLM key - reproduce it head-to-head on the same
questions with your own key via `python benchmarks/head_to_head.py` (one OpenRouter key works;
see [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) for the n=90 / n=205 runs, the paired
significance tests, and the published nulls). The full test suite runs in public CI (badge
above). The pitch isn't "trust me" - it's "run it."

## Add persistent memory to your agent in one line (MCP)

GENOME ships a **fully-local MCP server** - cross-session memory for Claude Desktop, Claude
Code, or Cursor with **no API key and no data leaving your machine**:

```bash
pip install "genome-memory[mcp]"
```

```json
{ "mcpServers": { "genome": { "command": "genome-mcp" } } }
```

Or zero-install via uv: `{ "command": "uvx", "args": ["--from", "genome-memory[mcp]", "genome-mcp"] }`

Tools the agent gets: **`remember`**, **`recall`**, **`forget`**, **`reset_memories`**.
Memories persist locally in `~/.genome/memories.db`. [Full MCP details ↓](#use-it-as-an-mcp-server-fully-local-memory-for-any-agent)

## GENOME vs Mem0 at a glance

| | GENOME | Mem0 |
|---|---|---|
| **Answer accuracy** (LoCoMo, LongMemEval) | tied | tied |
| **LLM calls to store one message** | **0** | 1+ |
| **Write speed** | **~10 ms** | ~2,000 ms |
| **Runs offline / air-gapped** | **yes** | no (needs an LLM API) |
| **Ingest cost** (10k-user deployment) | **~$190 / yr** | $159k-$1.6M / yr |
| **"What was true in March?"** (point-in-time) | **yes** | no |
| **Deterministic, auditable memory** | **yes** | no |

Every number is measured within one harness - same responder, judge, embedder, and top-k;
only the memory layer changes - with paired significance tests. Full detail and per-number
provenance: [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md). Formatted report:
[`benchmarks/GENOME-LoCoMo-Report.pdf`](./benchmarks/GENOME-LoCoMo-Report.pdf).

## Why it's ~1,000× cheaper: it never calls an LLM to remember

Storing one message costs **one LLM call in Mem0, zero in GENOME** (just a local embedding).
That's not a benchmark you can argue with - it's arithmetic, and it holds no matter which
LLM you price it against. At 10,000 users × 50 messages/day (15M messages/month):

| Model Mem0 uses to extract | Mem0's yearly ingest bill | GENOME |
|---|---|---|
| Claude Haiku | $1,601,757 | **$190** |
| gpt-4o-mini | $238,596 | **$190** |
| cheapest hosted model | $159,064 | **$190** |

The gap survives the cheapest model and *grows* in production (Mem0 re-sends stored memories
to the LLM as the store fills). Reproduce: `python benchmarks/tco_project.py` (no API key).

## It runs air-gapped

GENOME's default embedder is local. We proved the write path is genuinely offline by
**blocking all network during writes** - they still succeed:

- **~10 ms/message, 0 network calls, 0 LLM calls** (`python benchmarks/local_writepath.py`)
- Mem0 can't do this - it needs an LLM API call to ingest.

That makes GENOME usable on-prem, in regulated environments, or fully offline. It's a yes/no
capability, not a price point.

## How it works

- **Write:** embed the message locally and store it. No LLM, no network. (~10 ms)
- **Read:** vector search over your memories, with an optional local cross-encoder reranker
  for harder queries.
- **Optional bi-temporal layer:** track how facts change over time and answer "what was true
  at time T" - see below.

## What determinism buys you

Because nothing on the write path interprets your content, GENOME can do things an
LLM-ingest memory system cannot do in principle:

- **Memory firewall** (`genome.firewall`): tag