genome

GENOME

面向 AI Agent 的开放记忆。答案准确率与 Mem0 相同，但存储成本约低 1,000×，可完全离线运行，并保留可审计记录。

论文： Do Agents Need an LLM to Remember?（核心评估，2026）以及 What Does Each Memory Feature Buy?（对全部五项可选功能进行实测审计，涵盖成功与失败，2026）。PDF 文件位于 papers/；结果表位于 benchmarks/AUDIT-RESULTS.md。

大多数 Agent 记忆工具（如 Mem0）都会在每条消息上调用大模型，以决定要记住什么。这是耗时又昂贵的部分，而 GENOME 的核心判断是：其实并不需要这么做。GENOME 只在本地为每条消息生成嵌入：无需大模型、API，也无需在写入路径上访问网络。

在公开数据集（LoCoMo、LongMemEval）上进行了诚实的基准测试后，GENOME 的回答准确率与 Mem0 相同，但存储记忆的成本极低，而且可以完全离线运行。

先说明实情：在回答准确率方面，GENOME 与 Mem0 不相上下——我们不声称在这方面胜过它（六种独立的基准测试配置均确认了这一点，且差异在任一方向上都不显著）。GENOME 的优势在于成本、速度、离线运行，以及 Mem0 无法生成的时间记录和可审计记录。

查看运行效果

每一帧都是 examples/demo_timeline.py 的真实输出，由 tools/render_demo_gif.py 捕获。你也可以亲自运行，无需 API 密钥：

python examples/demo_timeline.py

有意思的是第 3 步。同一个问题会根据你询问的时间得到三个不同但正确的答案，因为存储会保留每条事实开始成立的时间，而不是将其覆盖：

问题	答案
Priya 在 2023 年 5 月住在哪里？	波士顿 [2023 年 3 月 - 2024 年 1 月]
Priya 在 2024 年 3 月住在哪里？	西雅图 [2024 年 1 月 - 2025 年 2 月]
Priya 现在住在哪里？	奥斯汀 [2025 年 2 月 - 至今]

“在考虑也许搬去丹佛，还没做决定”这段对话会被存储，但永远不会成为答案：这是一个计划，而非持久事实。

工作原理

写入路径刻意设计得简单、低成本。所有智能处理都发生在读取时，由查询来聚焦。

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

写入：在本地生成嵌入并存储。耗时约 10 ms，不调用大模型，不访问网络。嵌入是确定性的——相同文本始终生成相同向量，不会经过抽样提取步骤来判定哪些内容重要——因此存储内容由输入决定，重放日志可以精确还原存储内容。（ID 和时间戳会在每次写入时生成，因此对同一对话进行两次独立导入，内容和向量会一致，但记录 ID 不会一致。）

读取：在租户范围内进行精确余弦相似度搜索（无需构建或更新 ANN 索引），并可选择使用本地交叉编码器重排序器。

双时态层（可选）：按每条事实的领域时间记录，即它在现实世界中开始成立的时刻，而非导入时刻。这样，即使事实以乱序到达，也能回答特定时间点的问题。

为什么记录可以重新推导

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

无法重新推导的记录很难审计。这种属性，而非准确性，才是这一设计的真正理由。

不相信？亲自验证

成本、速度和离线方面的说法无需 API 密钥——用 60 秒在你自己的机器上测量：

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

首次运行会先下载本地嵌入模型（约 90 MB，仅需一次），然后才会打印任何内容，因此在冷启动的机器上，可能会出现 30-120 秒看似无响应的情况。此后的每次运行都会立即完成。

它会在物理阻断出站网络的情况下写入记忆，并打印实时通过／失败回执——0 次网络调用、0 次大模型调用、个位数毫秒的写入耗时，以及正常工作的检索：

  [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

这份回执只涵盖成本／速度／离线方面的说明。与 Mem0 准确率持平的说法需要单独进行更大规模的验证，并且需要大模型密钥——使用你自己的密钥，通过 python benchmarks/head_to_head.py 针对相同问题进行正面对比复现（一个 OpenRouter 密钥即可；n=90／n=205 的运行结果、配对显著性检验和已公布的无显著差异结果，见 benchmarks/RESULTS.md）。完整测试套件在公开 CI 中运行（见上方徽章）。我们的主张不是“相信我”，而是“亲自运行”。

一行代码为你的 Agent 添加持久记忆（MCP）

GENOME 提供完全本地运行的 MCP 服务——为 Claude Desktop、Claude Code 或 Cursor 提供跨会话记忆，无需 API 密钥，数据也不会离开你的机器：

pip install "genome-memory[mcp]"

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

也可以通过 uv 零安装运行：{ "command": "uvx", "args": ["--from", "genome-memory[mcp]", "genome-mcp"] }

Agent 可使用的工具：remember、recall、forget、reset_memories。 记忆会持久保存在本地的 ~/.genome/memories.db 中。查看完整 MCP 详情 ↓

GENOME 与 Mem0 一览

	GENOME	Mem0
回答准确率（LoCoMo、LongMemEval）	持平	持平
存储一条消息所需的大模型调用次数	0	1+
写入速度	约 10 ms	约 2,000 ms
支持离线／隔离网络运行	是	否（需要大模型 API）
摄取成本（部署规模为 10k 用户）	约 $190／年	$159k-$1.6M／年
“3 月份哪些内容为真？”（时间点查询）	是	否
确定性、可审计的记忆	是	否

所有数字都在同一个测试框架内测得——使用相同的回答模型、评判模型、嵌入模型和 top-k，仅更换记忆层，并进行了配对显著性检验。完整详情和各数字的来源：benchmarks/RESULTS.md。格式化报告：benchmarks/GENOME-LoCoMo-Report.pdf。

为什么成本低约 1,000 倍：记忆时从不调用大模型

存储一条消息，Mem0 需要 1 次大模型调用，GENOME 需要 0 次（只做本地嵌入）。 这是无法争辩的基准——它只是算术，无论你按哪种大模型的价格计算都成立。按 10,000 名用户 × 每天 50 条消息（每月 15M 条消息）计算：

Mem0 用于提取的模型	Mem0 年度摄取费用	GENOME
Claude Haiku	$1,601,757	$190
gpt-4o-mini	$238,596	$190
最便宜的托管模型	$159,064	$190

即使使用最便宜的模型，差距依然存在，而且在生产环境中还会扩大（随着存储内容增加，Mem0 会把已存储的记忆重新发送给大模型）。复现方法：python benchmarks/tco_project.py（无需 API 密钥）。

支持隔离网络环境运行

GENOME 的默认嵌入模型在本地运行。我们通过在写入期间阻断所有网络，证明写入流程确实可以离线运行——写入仍然成功：

• 约 10 ms／条消息、0 次网络调用、0 次大模型调用（python benchmarks/local_writepath.py）
• Mem0 无法做到这一点——它需要调用大模型 API 才能摄取内容。

因此，GENOME 可用于本地部署、受监管环境或完全离线的场景。这是一项是／否的能力，而非价格优势。

工作原理

• **写入：**在本地嵌入消息并存储。不使用大模型，不访问网络。（约 10 ms）
• **读取：**对记忆进行向量搜索；对于较难的查询，可选择使用本地交叉编码器重排器。
• **可选的双时态层：**跟踪事实随时间的变化，并回答“在时间 T 时什么为真”——详见下文。

确定性带来的优势

由于写入路径上的任何环节都不会解读你的内容，GENOME 能做到一些原则上 LLM 摄取式记忆系统无法做到的事：

• 记忆防火墙（genome.firewall）：为每次写入标记其来源（user、agent、tool、web），将低信任来源隔离，避免其被检索，并执行来源绑定的权限控制——即使提示词注入的冲突解决器要求这样做，网页内容也永远无法 UPDATE 或 DELETE 用户说过的话。注入内容也没有可攻击的提取步骤：写入路径中没有大模型。

  from genome import Memory
  from genome.firewall import TrustPolicy
  
  m = Memory(trust_policy=TrustPolicy(recall_min_trust=1))
  m.add("I live in Anchorage", user_id="u1", provenance="user")
  m.add(scraped_page_text, user_id="u1", provenance="web")   # quarantined
  

• 可解释的检索（genome.explain）：explain_search() 会报告每个候选项的密集向量分数、BM25 排名、融合分数；如果某个候选项未被返回，还会给出确切原因（被父级过滤、被隔离、超出限制）。两次运行的结果一致，因此检索错误可以作为回归测试提交，而不必无奈地耸耸肩。

• 日志与重放（genome.journal）：记录每次变更，并以可验证的方式重现存储内容——verify_journal() 会重放历史记录并比较规范哈希。重放日志前缀即可回滚；重放到不同存储中，即可为假设场景运行创建记忆分支。日志位于提取步骤之后，因此即使配置了大模型提取器，重放结果仍然是确定的。每行都与前一行相链接，因此即使改动在最终状态中相互抵消，也能检测到行被删除或编辑的情况。

  # Tamper-EVIDENT by default. Pass a key (kept outside the journal's directory)
  # to make it tamper-PROOF: an unkeyed chain can be recomputed by anyone with
  # write access, an HMAC chain cannot.
  m = Memory(journal="mem.journal", journal_key=os.environb[b"GENOME_JOURNAL_KEY"])
  

• 多 Agent 信念归属（record_fact(..., believed_by="agent-a")）：共享存储的 Agent 各自保留自己的信念时间线——Agent B 的不同意见不会覆盖 Agent A 的事实——而 belief_conflicts() 会呈现分歧，供人有意解决，而不是悄悄选定赢家。

• 中立的基准测试框架（benchmarks/neutral/）：使用相同的响应器、评判器和嵌入器运行 GENOME、Mem0 和完整上下文基线，并提供成对 McNemar 矩阵和完整披露区块。GENOME 只是表格中的一行，而不是主场。

安装

pip install genome-memory

默认嵌入器在本地运行（sentence-transformers/all-MiniLM-L6-v2），无需 API 密钥，可离线使用；首次运行时会下载约 90 MB 的模型。也可选用 OpenAI 嵌入，以实现更高维度的检索。

**如实说明依赖：**核心安装依赖 numpy、sentence-transformers、scikit-learn 和 rank-bm25。本地嵌入使用 PyTorch（由 sentence-transformers 引入），因此安装并不轻量——这是为离线、零成本嵌入而有意作出的权衡。绘图和基准测试图表依赖位于可选的 [viz] 扩展中，不属于核心依赖。要从 Mem0 迁移？请参阅 docs/migrating_from_mem0.md。

快速入门（完全本地，无需 API 密钥）

from genome import Memory

mem = Memory(storage="genome.db")   # local embedder by default; ":memory:" for ephemeral

# Store a message -- embedded locally, no LLM call, no network
mem.add("Ada met Lin at the robotics summit in Berlin.", user_id="u1")
mem.add("They are collaborating on an open-source planning library.", user_id="u1")

# Retrieve the most relevant memories
for hit in mem.search("Where did Ada meet Lin?", user_id="u1", limit=5):
    print(f"{hit.score:.3f}  {hit.content}")

Memory 的 API 与 Mem0 一致（add / search / get / delete / reset）——几乎可以直接替换。若要改用 OpenAI 嵌入（设置 OPENAI_API_KEY）：

from genome import Memory, EmbeddingProvider
mem = Memory(storage="genome.db",
             embedding_provider=EmbeddingProvider(model_name="openai:text-embedding-3-small"))

将其用作 MCP 服务（为任何 Agent 提供完全本地的记忆）

GENOME 内置了 MCP 服务，因此任何 MCP 客户端（Claude Desktop、Claude Code、Cursor 等）都能获得持久的跨会话记忆，且完全在本地计算机上运行——不调用大模型、不需要 API 密钥、数据不会离开本机。大多数记忆 MCP 都无法做到这一点。

安装 mcp extra，然后将其添加到客户端的配置中：

pip install "genome-memory[mcp]"

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

Agent 可用的工具：remember（存储事实/偏好，本地运行且不调用大模型）、recall（语义搜索）、forget（删除与查询匹配的记忆）、reset_memories（清除用户的记忆）。记忆保存在 ~/.genome/memories.db 中（可通过 GENOME_MCP_DB 环境变量覆盖）。使用 genome-mcp 或 python -m genome.mcp.server 独立运行。

将其作为 HTTP API 运行

更喜欢 HTTP？GENOME 内置了一个 FastAPI 服务，其接口与库一一对应（add / search / get / update / delete / reset / synthesize），并在 /docs 提供自动生成的 OpenAPI 规范。

pip install "genome-memory[fastapi]"

在本地试用（无需密钥，仅限回环接口——一个标志即可明确表示“无身份验证”的意图）：

GENOME_ALLOW_NO_AUTH=1 python -m genome.server        # serves on 127.0.0.1:8080

curl -X POST localhost:8080/v1/memories \
  -H 'Content-Type: application/json' \
  -d '{"text": "Ada met Lin at the robotics summit in Berlin.", "user_id": "u1"}'

curl -X POST localhost:8080/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "Where did Ada meet Lin?", "user_id": "u1", "limit": 5}'

默认安全。 除非像上文那样选择启用，否则服务不会在未经过身份验证的情况下提供服务；没有密钥时，也不会绑定到非回环接口。若要对外开放，请设置 API 密钥（通过 X-API-Key 发送）——绑定到 localhost 以外的地址时必须设置：

GENOME_API_KEY=$(openssl rand -hex 32) GENOME_HOST=0.0.0.0 python -m genome.server
# then add:  -H "X-API-Key: $GENOME_API_KEY"  to every request

对于多租户部署，设置 GENOME_REQUIRE_SCOPE=1，以要求每次调用都提供 user_id/agent_id，并禁用全局重置。Docker：docker-compose up（需要 GENOME_API_KEY 和 POSTGRES_PASSWORD；Postgres 仅发布到回环接口）。完整指南（包括 Postgres 后端和所有环境变量）：docs/tutorial_quickstart.md。

TypeScript / JavaScript 客户端

@northtek/genome-memory 通过此服务提供与 Python Memory API 形态一致的接口（ESM，Node 20+ 或浏览器）：

npm install @northtek/genome-memory

import { Memory } from "@northtek/genome-memory";

const mem = new Memory({ baseUrl: "http://localhost:8080" });
await mem.add({ text: "Ada met Lin in Berlin.", userId: "u1" });
const hits = await mem.search({ query: "Where did Ada meet Lin?", userId: "u1" });

完整的客户端文档：sdks/typescript/README.md。

真实的测试结果

所有系统使用相同的响应器、评审器和嵌入模型；只有记忆层不同。

测量项目	结果	结论
窗口内的回答准确率（LoCoMo）	GENOME 0.851 vs Mem0 0.855（p > 0.23）	持平
难度更高的基准测试中的回答准确率（LongMemEval，n=90 和 n=205）	趋势上领先，但不显著（p = 0.14-0.19）	持平
历史记录超出上下文窗口时的准确率	上下文减少 80 倍时，+0.409（p = 8e-10）	胜出
存储一条消息的成本	0 次大模型调用 vs 1 次以上；便宜 837-8,433 倍	胜出
写入路径	约 10 ms，物理隔离，0 次网络调用	胜出
时间点查询（“T 时刻的情况如何”）	信念状态 0.870 vs Mem0 0.676（合成数据）	胜出，但有注意事项
使用重排序时的检索命中率	hit@10 提升（最高达 0.943）；本地且免费	胜出

我们测试过但没有帮助的方案（这样你就不必再试）

我们会公开无效结果——这能证明胜出的结果是真实的：

• **综合 / 整合：**在相同 token 预算下，对准确率没有影响（p = 0.86）。
• **混合检索（BM25 + dense）和图检索：**在 LoCoMo 上，混合检索表现不如纯 dense；此处未验证图检索。
• **重排序对准确率的提升取决于嵌入模型：**它能稳定提升检索命中率，但对最终回答准确率的影响取决于嵌入模型——应将其视为提升检索质量的工具，而非保证提升准确率的方案。

双时态记忆：“时间 T 时什么为真”

GENOME 可以追踪事实如何随时间变化，并回答特定时间点的问题——基于覆盖的记忆在结构上无法做到这一点（它只保留最新值）：

from genome.memory.belief import ingest_belief_turn, answer_belief_context

mem = Memory(storage="genome.db", llm_call=my_llm_fn)

# facts land at their DOMAIN time (parsed from the text), not wall-clock ingest time
ingest_belief_turn(mem, "In March 2024, Jordan moved to Seattle.", session_time=t0, user_id="u")
ingest_belief_turn(mem, "Jordan just moved to Austin.", session_time=t2, user_id="u")

answer_belief_context(mem, "Where does Jordan live now?", user_id="u")            # -> Austin
answer_belief_context(mem, "Where did Jordan live in early 2024?", user_id="u")   # -> Seattle
answer_belief_context(mem, "List every city Jordan has lived in.", user_id="u")   # -> Seattle; Austin

在 TempBelief 基准测试中，它回答特定时间点查询的得分为 0.870，而 Mem0 为 0.676；知识图谱经审计后的精确率为 0.97，召回率为 0.96。注意： TempBelief 使用带有明确日期的合成文本；在自然语音上的差距会缩小。这项能力确实存在，但证据范围有限。

可选功能

按需启用；默认路径在摄取时无需使用大模型，并且在本地运行。

mem = Memory(
    storage="genome.db",
    llm_call=my_llm_fn,             # LLM-based fact extraction on add()
    resolve_conflicts=True,         # ADD/UPDATE/DELETE vs existing memories
    auto_extract_entities=True,     # entity graph for graph retrieval
    auto_consolidate_threshold=200, # summarize-or-prune when a scope grows past N
)
mem.search("...", user_id="u1", mode="hybrid")   # modes: "dense" (default), "hybrid", "graph"

重排序（本地、免费、无需 API）：

from genome.memory.rerank import CrossEncoderReranker
mem = Memory(storage="genome.db", reranker=CrossEncoderReranker())   # lazy-loaded
mem.search("Where did the user go on vacation?", user_id="u1", limit=5)  # reranked

复现基准测试

LoCoMo 和 LongMemEval 数据集不随项目提供（它们各自有自己的许可证——LoCoMo 使用 CC BY-NC 4.0）。请参阅 benchmarks/data/README.md 下载。前两行无需数据集或 API 密钥：

python benchmarks/local_writepath.py        # local write path: ~10ms/msg, 0 network
python benchmarks/tco_project.py            # deployment cost projection
python benchmarks/verdict.py                # in-window accuracy + McNemar
python benchmarks/haystack_report.py        # overflow / context-window crossover
python benchmarks/ingest_cost.py --n 80     # measured ingestion cost vs Mem0
python benchmarks/lme_qa.py --n 90          # LongMemEval head-to-head vs Mem0
python benchmarks/tempbelief_run.py --convs 6   # bi-temporal point-in-time vs baselines

支持与商业版

报告错误和提问：请访问 issues 和 discussions。社区支持尽力而为——详情请参阅 SUPPORT.md。

GENOME Enterprise 是一款独立的商业产品，面向受监管行业和本地部署的客户；这些客户必须向审计人员说明 AI 系统在何时知道了什么：防篡改的哈希链审计记录、特定时间点重建、合规报告、带有擦除证明的保留策略、RBAC 和 SSO。可自托管，按部署授权——我们刻意不提供托管版本，因为它的价值就在于数据永不离开您的环境。该版本为本项目提供资金支持。正在评估它，或希望为开源核心获取商业支持？ [email protected]

许可证

Apache License 2.0——请参阅 LICENSE 和 NOTICE。

GENOME 免费且开源：您可以阅读、修改、自行托管，并将其嵌入自己的应用程序——包括商业用途——但须遵守 Apache 2.0 的条款。我们无意采用“开放核心诱饵换招”策略：核心将继续采用 Apache-2.0 许可证。

Apache-2.0 授予的权利适用于代码，不适用于名称——请参阅 TRADEMARKS.md，其中首先说明了无需征求许可即可进行的操作。 如有疑问：[email protected]。

Copyright 2026 Northtek (FrostByte Digital LLC)。 mcp-name: io.github.NORTHTEKDevs/genome