{
"markdown": "# GENOME\n\n**Open memory for AI agents. Same answer accuracy as Mem0 - but ~1,000× cheaper to store, runs fully offline, and keeps an auditable record.**\n\n[](https://github.com/NORTHTEKDevs/genome/actions/workflows/tests.yml)\n[](https://github.com/NORTHTEKDevs/genome/actions/workflows/install-canary.yml)\n[](https://pypi.org/project/genome-memory/)\n[](./LICENSE)\n\n[](https://doi.org/10.5281/zenodo.21987934)\n\n**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).\n\nMost agent-memory tools (like Mem0) call an LLM on **every message** to decide what to\nremember. That's the slow, expensive part - and GENOME's bet is that you don't need it.\nGENOME just embeds each message locally: no LLM, no API, no network in the write path.\n\nBenchmarked honestly on public datasets (LoCoMo, LongMemEval), GENOME **answers just as\naccurately as Mem0** - while storing memories for a tiny fraction of the cost and running\ncompletely offline.\n\n> **Honest up front:** on answer accuracy, GENOME *ties* Mem0 - we do **not** claim to beat\n> it there (six independent benchmark configurations confirm parity, none significant in\n> either direction). The advantage is cost, speed, offline operation, and a\n> temporal/auditable record Mem0 can't produce.\n\n## See it work\n\n\n\nEvery frame is real output from [`examples/demo_timeline.py`](./examples/demo_timeline.py),\ncaptured by [`tools/render_demo_gif.py`](./tools/render_demo_gif.py). Run it yourself,\nno API key required:\n\n```bash\npython examples/demo_timeline.py\n```\n\nThe interesting part is step 3. The same question gets three different correct answers\ndepending on *when* you ask about, because the store keeps when each fact became true\nrather than overwriting it:\n\n| Question | Answer |\n|---|---|\n| What was Priya's city in May 2023? | Boston [Mar 2023 - Jan 2024] |\n| What was Priya's city in March 2024? | Seattle [Jan 2024 - Feb 2025] |\n| What is Priya's city now? | Austin [Feb 2025 - present] |\n\nThe \"thinking about maybe moving to Denver, nothing decided\" turn is stored but never\nbecomes an answer: it is a plan, not a durable fact.\n\n## How it works\n\nThe write path is deliberately dumb and cheap. All the intelligence happens at read time,\nwhen there is a query to focus it.\n\n```mermaid\nflowchart LR\n M[\"incoming message\"] --> E[\"local embedder
all-MiniLM-L6-v2\"]\n E --> S[(\"local store
SQLite or Postgres\")]\n M -. \"optional, opt-in\" .-> B[\"belief extraction
(the only LLM call)\"]\n B --> K[(\"bi-temporal
fact log\")]\n\n Q[\"query\"] --> R[\"exact cosine search
over this tenant's rows\"]\n S --> R\n R --> RR[\"optional cross-encoder
rerank\"]\n RR --> A[\"context for the agent\"]\n Q --> PIT[\"as-of resolution
facts_valid_at(entity, T)\"]\n K --> PIT\n PIT --> A\n\n style E fill:#0A84FF,color:#fff\n style S fill:#1c2530,color:#fff\n style K fill:#1c2530,color:#fff\n style B fill:#3a3a3a,color:#fff\n```\n\nWrite: embed locally, store. About 10 ms, zero LLM calls, zero network calls. The\nembedding is deterministic -- the same text always yields the same vector, with no\nsampled extraction step deciding what matters -- so what gets stored is a function\nof the input, and replaying a journal reproduces that store exactly. (Ids and\ntimestamps are stamped per write, so two independent ingests of the same\nconversation agree on content and vectors, not on record ids.)\n\nRead: exact cosine search within the tenant's scope (no ANN index to build or update),\nwith an optional local cross-encoder reranker.\n\nBi-temporal layer (opt-in): records each fact at its **domain time**, the moment it became\ntrue in the world, not the moment it was ingested. That is what makes point-in-time\nquestions answerable even when facts arrive out of order.\n\n### Why the record can be re-derived\n\n```mermaid\nflowchart TB\n subgraph LLM[\"LLM-extraction memory\"]\n A1[\"message\"] --> A2[\"LLM decides what matters
(sampled, non-deterministic)\"]\n A2 --> A3[(\"store\")]\n A3 --> A4[\"replaying the same input
can produce a different store\"]\n end\n subgraph GEN[\"GENOME\"]\n B1[\"message\"] --> B2[\"local embedding
(deterministic)\"]\n B2 --> B3[(\"store\")]\n B3 --> B4[\"replaying the same input
reproduces the same store\"]\n end\n style A4 fill:#5c1f1f,color:#fff\n style B4 fill:#1f4d33,color:#fff\n```\n\nA record that cannot be re-derived is difficult to audit. That property, not accuracy, is\nthe actual argument for this design.\n\n## Don't believe it? Prove it yourself\n\nThe **cost, speed, and offline** claims need no API key - measure them on *your* machine in 60 seconds:\n\n```bash\ngit clone https://github.com/NORTHTEKDevs/genome && cd genome\npip install -e . && python -m genome.verify\n```\n\nThe **first** run downloads the local embedding model (~90 MB, one time) before printing\nanything, so expect 30-120 seconds of apparent silence on a cold machine. Every run after\nthat is instant.\n\nIt writes memories with your **outbound network physically blocked** and prints a live\npass/fail receipt - 0 network calls, 0 LLM calls, single-digit-ms writes, retrieval that works:\n\n```\n [PASS] Air-gapped write path: wrote 200 memories with every outbound socket blocked -> 0 network attempts, 0 LLM calls\n [PASS] Write latency: 7.1 ms/message (Mem0's measured write path: ~2,055 ms + 1 LLM call/message)\n [PASS] Retrieval works: top hit score 0.598\n```\n\nThat receipt covers the cost/speed/offline story only. The **accuracy-parity with Mem0** claim\nis a separate, larger check that needs an LLM key - reproduce it head-to-head on the same\nquestions with your own key via `python benchmarks/head_to_head.py` (one OpenRouter key works;\nsee [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md) for the n=90 / n=205 runs, the paired\nsignificance tests, and the published nulls). The full test suite runs in public CI (badge\nabove). The pitch isn't \"trust me\" - it's \"run it.\"\n\n## Add persistent memory to your agent in one line (MCP)\n\nGENOME ships a **fully-local MCP server** - cross-session memory for Claude Desktop, Claude\nCode, or Cursor with **no API key and no data leaving your machine**:\n\n```bash\npip install \"genome-memory[mcp]\"\n```\n\n```json\n{ \"mcpServers\": { \"genome\": { \"command\": \"genome-mcp\" } } }\n```\n\nOr zero-install via uv: `{ \"command\": \"uvx\", \"args\": [\"--from\", \"genome-memory[mcp]\", \"genome-mcp\"] }`\n\nTools the agent gets: **`remember`**, **`recall`**, **`forget`**, **`reset_memories`**.\nMemories persist locally in `~/.genome/memories.db`. [Full MCP details ↓](#use-it-as-an-mcp-server-fully-local-memory-for-any-agent)\n\n## GENOME vs Mem0 at a glance\n\n| | GENOME | Mem0 |\n|---|---|---|\n| **Answer accuracy** (LoCoMo, LongMemEval) | tied | tied |\n| **LLM calls to store one message** | **0** | 1+ |\n| **Write speed** | **~10 ms** | ~2,000 ms |\n| **Runs offline / air-gapped** | **yes** | no (needs an LLM API) |\n| **Ingest cost** (10k-user deployment) | **~$190 / yr** | $159k-$1.6M / yr |\n| **\"What was true in March?\"** (point-in-time) | **yes** | no |\n| **Deterministic, auditable memory** | **yes** | no |\n\nEvery number is measured within one harness - same responder, judge, embedder, and top-k;\nonly the memory layer changes - with paired significance tests. Full detail and per-number\nprovenance: [`benchmarks/RESULTS.md`](./benchmarks/RESULTS.md). Formatted report:\n[`benchmarks/GENOME-LoCoMo-Report.pdf`](./benchmarks/GENOME-LoCoMo-Report.pdf).\n\n## Why it's ~1,000× cheaper: it never calls an LLM to remember\n\nStoring one message costs **one LLM call in Mem0, zero in GENOME** (just a local embedding).\nThat's not a benchmark you can argue with - it's arithmetic, and it holds no matter which\nLLM you price it against. At 10,000 users × 50 messages/day (15M messages/month):\n\n| Model Mem0 uses to extract | Mem0's yearly ingest bill | GENOME |\n|---|---|---|\n| Claude Haiku | $1,601,757 | **$190** |\n| gpt-4o-mini | $238,596 | **$190** |\n| cheapest hosted model | $159,064 | **$190** |\n\nThe gap survives the cheapest model and *grows* in production (Mem0 re-sends stored memories\nto the LLM as the store fills). Reproduce: `python benchmarks/tco_project.py` (no API key).\n\n## It runs air-gapped\n\nGENOME's default embedder is local. We proved the write path is genuinely offline by\n**blocking all network during writes** - they still succeed:\n\n- **~10 ms/message, 0 network calls, 0 LLM calls** (`python benchmarks/local_writepath.py`)\n- Mem0 can't do this - it needs an LLM API call to ingest.\n\nThat makes GENOME usable on-prem, in regulated environments, or fully offline. It's a yes/no\ncapability, not a price point.\n\n## How it works\n\n- **Write:** embed the message locally and store it. No LLM, no network. (~10 ms)\n- **Read:** vector search over your memories, with an optional local cross-encoder reranker\n for harder queries.\n- **Optional bi-temporal layer:** track how facts change over time and answer \"what was true\n at time T\" - see below.\n\n## What determinism buys you\n\nBecause nothing on the write path interprets your content, GENOME can do things an\nLLM-ingest memory system cannot do in principle:\n\n- **Memory firewall** (`genome.firewall`): tag every write with where it came from\n (`user`, `agent`, `tool`, `web`), quarantine low-trust origins from recall, and\n enforce origin-bound authority - web content can never UPDATE or DELETE what your\n user said, even when a prompt-injected conflict resolver asks for it. There is\n also no extraction step for injected content to attack: the write path has no LLM.\n\n ```python\n from genome import Memory\n from genome.firewall import TrustPolicy\n\n m = Memory(trust_policy=TrustPolicy(recall_min_trust=1))\n m.add(\"I live in Anchorage\", user_id=\"u1\", provenance=\"user\")\n m.add(scraped_page_text, user_id=\"u1\", provenance=\"web\") # quarantined\n ```\n\n- **Explainable recall** (`genome.explain`): `explain_search()` reports every\n candidate's dense score, BM25 rank, fused score, and - when it was not returned -\n the exact reason (parent-filtered, quarantined, beyond the limit). Two runs agree,\n so a recall bug can be committed as a regression test instead of a shrug.\n\n- **Journal + replay** (`genome.journal`): record every mutation and provably\n reproduce the store - `verify_journal()` replays the history and compares\n canonical hashes. Replay a prefix to roll back; replay into different storage to\n branch a memory for a what-if run. The journal sits after extraction, so replay\n is deterministic even if you configured an LLM extractor. Each line chains to its\n predecessor, so a removed or edited line is detected even when the change cancels\n out in the final state.\n\n ```python\n # Tamper-EVIDENT by default. Pass a key (kept outside the journal's directory)\n # to make it tamper-PROOF: an unkeyed chain can be recomputed by anyone with\n # write access, an HMAC chain cannot.\n m = Memory(journal=\"mem.journal\", journal_key=os.environb[b\"GENOME_JOURNAL_KEY\"])\n ```\n\n- **Multi-agent belief attribution** (`record_fact(..., believed_by=\"agent-a\")`):\n agents sharing a store keep their own belief timelines - agent B disagreeing does\n not clobber agent A's fact - and `belief_conflicts()` surfaces disagreements for\n deliberate resolution instead of silently picking a winner.\n\n- **A neutral benchmark harness** (`benchmarks/neutral/`): run GENOME, Mem0, and a\n full-context baseline through the same responder, judge, and embedder, with a\n pairwise McNemar matrix and a full-disclosure block. GENOME is one row in the\n table, not the house.\n\n## Install\n\n```bash\npip install genome-memory\n```\n\nThe default embedder is local (`sentence-transformers/all-MiniLM-L6-v2`) - no API key,\nworks offline; the first run downloads the ~90 MB model once. OpenAI embeddings are\noptional for higher-dimensional retrieval.\n\n**Dependency footprint, honestly:** the core install is `numpy`, `sentence-transformers`,\n`scikit-learn`, and `rank-bm25`. Local embeddings run on PyTorch (pulled in by\nsentence-transformers), so it isn't a tiny install - that's the deliberate tradeoff for\noffline, zero-cost embedding. Plotting/benchmark-chart deps live in an optional `[viz]`\nextra, not the core. Migrating from Mem0? See\n**[docs/migrating_from_mem0.md](docs/migrating_from_mem0.md)**.\n\n## Quickstart (fully local, no API key)\n\n```python\nfrom genome import Memory\n\nmem = Memory(storage=\"genome.db\") # local embedder by default; \":memory:\" for ephemeral\n\n# Store a message -- embedded locally, no LLM call, no network\nmem.add(\"Ada met Lin at the robotics summit in Berlin.\", user_id=\"u1\")\nmem.add(\"They are collaborating on an open-source planning library.\", user_id=\"u1\")\n\n# Retrieve the most relevant memories\nfor hit in mem.search(\"Where did Ada meet Lin?\", user_id=\"u1\", limit=5):\n print(f\"{hit.score:.3f} {hit.content}\")\n```\n\n`Memory` mirrors Mem0's API (`add` / `search` / `get` / `delete` / `reset`) - a near\ndrop-in swap. To use OpenAI embeddings instead (set `OPENAI_API_KEY`):\n\n```python\nfrom genome import Memory, EmbeddingProvider\nmem = Memory(storage=\"genome.db\",\n embedding_provider=EmbeddingProvider(model_name=\"openai:text-embedding-3-small\"))\n```\n\n## Use it as an MCP server (fully-local memory for any agent)\n\nGENOME ships an MCP server, so any MCP client (Claude Desktop, Claude Code, Cursor, ...) gets\npersistent cross-session memory that runs **entirely on the local machine** - no LLM calls,\nno API keys, no data leaves the box. Most memory MCPs can't say that.\n\nInstall with the `mcp` extra, then add it to your client's config:\n\n```bash\npip install \"genome-memory[mcp]\"\n```\n\n```json\n{\n \"mcpServers\": {\n \"genome\": { \"command\": \"genome-mcp\" }\n }\n}\n```\n\nTools the agent gets: **`remember`** (store a fact/preference, local + 0 LLM), **`recall`**\n(semantic search), **`forget`** (delete the memory matching a query), **`reset_memories`**\n(clear a user's memories). Memories persist in `~/.genome/memories.db` (override with the\n`GENOME_MCP_DB` env var). Run standalone with `genome-mcp` or `python -m genome.mcp.server`.\n\n## Run it as an HTTP API\n\nPrefer HTTP? GENOME ships a FastAPI server that mirrors the library 1:1 (`add` / `search` /\n`get` / `update` / `delete` / `reset` / `synthesize`), with an auto-generated OpenAPI spec at\n`/docs`.\n\n```bash\npip install \"genome-memory[fastapi]\"\n```\n\n**Try it locally** (keyless, loopback only - one flag makes the \"no auth\" intent explicit):\n\n```bash\nGENOME_ALLOW_NO_AUTH=1 python -m genome.server # serves on 127.0.0.1:8080\n```\n\n```bash\ncurl -X POST localhost:8080/v1/memories \\\n -H 'Content-Type: application/json' \\\n -d '{\"text\": \"Ada met Lin at the robotics summit in Berlin.\", \"user_id\": \"u1\"}'\n\ncurl -X POST localhost:8080/v1/search \\\n -H 'Content-Type: application/json' \\\n -d '{\"query\": \"Where did Ada meet Lin?\", \"user_id\": \"u1\", \"limit\": 5}'\n```\n\n**Safe by default.** The server refuses to serve unauthenticated unless you opt in as\nabove, and it will not bind a non-loopback interface without a key. To expose it, set an\nAPI key (sent as `X-API-Key`) - required to bind beyond localhost:\n\n```bash\nGENOME_API_KEY=$(openssl rand -hex 32) GENOME_HOST=0.0.0.0 python -m genome.server\n# then add: -H \"X-API-Key: $GENOME_API_KEY\" to every request\n```\n\nFor multi-tenant deployments, set `GENOME_REQUIRE_SCOPE=1` to require `user_id`/`agent_id` on\nevery call and disable the global reset. Docker: `docker-compose up` (needs `GENOME_API_KEY`\nand `POSTGRES_PASSWORD`; Postgres is published on loopback only). Full guide, including the\nPostgres backend and every env var: [`docs/tutorial_quickstart.md`](./docs/tutorial_quickstart.md).\n\n### TypeScript / JavaScript client\n\n[`@northtek/genome-memory`](https://www.npmjs.com/package/@northtek/genome-memory) mirrors the\nPython `Memory` API shape against this server (ESM, Node 20+ or browser):\n\n```bash\nnpm install @northtek/genome-memory\n```\n\n```ts\nimport { Memory } from \"@northtek/genome-memory\";\n\nconst mem = new Memory({ baseUrl: \"http://localhost:8080\" });\nawait mem.add({ text: \"Ada met Lin in Berlin.\", userId: \"u1\" });\nconst hits = await mem.search({ query: \"Where did Ada meet Lin?\", userId: \"u1\" });\n```\n\nFull client docs: [`sdks/typescript/README.md`](./sdks/typescript/README.md).\n\n## The honest results\n\nSame responder + judge + embedder for every system; only the memory layer changes.\n\n| What we measured | Result | Verdict |\n|---|---|---|\n| Answer accuracy, in-window (LoCoMo) | GENOME 0.851 vs Mem0 0.855 (p > 0.23) | **Tied** |\n| Answer accuracy, harder bench (LongMemEval, n=90 & n=205) | directionally ahead, not significant (p = 0.14-0.19) | **Tied** |\n| Accuracy when history overflows the context window | **+0.409** at 80× less context (p = 8e-10) | **Win** |\n| Cost to store a message | 0 LLM calls vs 1+; **837-8,433× cheaper** | **Win** |\n| Write path | **~10 ms, air-gapped**, 0 network calls | **Win** |\n| Point-in-time (\"what was true at T\") | belief-state **0.870** vs Mem0 0.676 (synthetic data) | **Win, with caveat** |\n| Retrieval hit-rate with reranking | improves hit@10 (up to 0.943); local + free | **Win** |\n\n### What we tested that *didn't* help (so you don't have to)\n\nWe publish our nulls - it's how you know the wins are real:\n- **Synthesis / consolidation:** accuracy-neutral at equal token budget (p = 0.86).\n- **Hybrid (BM25 + dense) and graph retrieval:** hybrid underperformed plain dense on LoCoMo;\n graph was not validated here.\n- **Reranking's accuracy gain is embedder-dependent:** it reliably improves *retrieval\n hit-rate*, but its effect on final *answer accuracy* depends on the embedder - treat it as a\n retrieval-quality tool, not a guaranteed accuracy win.\n\n## Bi-temporal memory: \"what was true at time T\"\n\nGENOME can track how facts change over time and answer point-in-time questions - something\noverwrite-based memory structurally can't do (it only keeps the latest value):\n\n```python\nfrom genome.memory.belief import ingest_belief_turn, answer_belief_context\n\nmem = Memory(storage=\"genome.db\", llm_call=my_llm_fn)\n\n# facts land at their DOMAIN time (parsed from the text), not wall-clock ingest time\ningest_belief_turn(mem, \"In March 2024, Jordan moved to Seattle.\", session_time=t0, user_id=\"u\")\ningest_belief_turn(mem, \"Jordan just moved to Austin.\", session_time=t2, user_id=\"u\")\n\nanswer_belief_context(mem, \"Where does Jordan live now?\", user_id=\"u\") # -> Austin\nanswer_belief_context(mem, \"Where did Jordan live in early 2024?\", user_id=\"u\") # -> Seattle\nanswer_belief_context(mem, \"List every city Jordan has lived in.\", user_id=\"u\") # -> Seattle; Austin\n```\n\nOn the TempBelief benchmark it answers as-of queries at **0.870** vs Mem0's 0.676, with the\nknowledge graph audited at 0.97 precision / 0.96 recall. **Caveat:** TempBelief is synthetic\ntext with explicit dates; the edge shrinks on natural speech. Real capability, bounded proof.\n\n## Optional features\n\nOpt-in; the default path stays LLM-free and local at ingest.\n\n```python\nmem = Memory(\n storage=\"genome.db\",\n llm_call=my_llm_fn, # LLM-based fact extraction on add()\n resolve_conflicts=True, # ADD/UPDATE/DELETE vs existing memories\n auto_extract_entities=True, # entity graph for graph retrieval\n auto_consolidate_threshold=200, # summarize-or-prune when a scope grows past N\n)\nmem.search(\"...\", user_id=\"u1\", mode=\"hybrid\") # modes: \"dense\" (default), \"hybrid\", \"graph\"\n```\n\nReranking (local, free, no API):\n\n```python\nfrom genome.memory.rerank import CrossEncoderReranker\nmem = Memory(storage=\"genome.db\", reranker=CrossEncoderReranker()) # lazy-loaded\nmem.search(\"Where did the user go on vacation?\", user_id=\"u1\", limit=5) # reranked\n```\n\n## Reproduce the benchmarks\n\nThe LoCoMo and LongMemEval datasets are **not bundled** (they carry their own licenses - \nLoCoMo is CC BY-NC 4.0). See [`benchmarks/data/README.md`](./benchmarks/data/README.md) to\ndownload them. The first two lines need no dataset and no API keys:\n\n```bash\npython benchmarks/local_writepath.py # local write path: ~10ms/msg, 0 network\npython benchmarks/tco_project.py # deployment cost projection\npython benchmarks/verdict.py # in-window accuracy + McNemar\npython benchmarks/haystack_report.py # overflow / context-window crossover\npython benchmarks/ingest_cost.py --n 80 # measured ingestion cost vs Mem0\npython benchmarks/lme_qa.py --n 90 # LongMemEval head-to-head vs Mem0\npython benchmarks/tempbelief_run.py --convs 6 # bi-temporal point-in-time vs baselines\n```\n\n## Support and commercial tier\n\nBugs and questions: [issues](https://github.com/NORTHTEKDevs/genome/issues) and\n[discussions](https://github.com/NORTHTEKDevs/genome/discussions). Community support is\nbest-effort - see [SUPPORT.md](./SUPPORT.md).\n\n**GENOME Enterprise** is a separate commercial product for regulated and on-premise buyers\nwho have to answer to an auditor for what an AI system knew and when: a tamper-evident\nhash-chained audit record, point-in-time reconstruction, compliance reports, retention with\nerasure proofs, RBAC and SSO. Self-hosted and licensed per deployment - there is no hosted\nversion, deliberately, because the value is that your data never leaves. That tier is what\nfunds this one. Evaluating it, or want commercial support on the open core?\n**info@northtek.io**\n\n## License\n\n**Apache License 2.0** - see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).\n\nGENOME is free and open source: read it, modify it, self-host it, and embed it in your own\napplications - commercial use included - under the terms of Apache 2.0. There is no\n\"open core bait and switch\" planned: the core stays Apache-2.0.\n\nThe Apache-2.0 grant covers the code, not the name - see\n[TRADEMARKS.md](./TRADEMARKS.md), which leads with what you may do without asking.\nQuestions: info@northtek.io.\n\nCopyright 2026 Northtek (FrostByte Digital LLC).\nmcp-name: io.github.NORTHTEKDevs/genome\n",
"bytes": 22735,
"sha": "3f32b75528d80c002bc4a0350183ce7c09f5abc168c544267900bcfc950ffc32",
"repo_slug": "northtekdevs/genome",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_northtekdevs_genome_65d3dc61/readme"
}