MemoryGraph

你的智能体找到了一条相关记忆。MemoryGraph 会告诉它这条记忆是否仍然为真。

MemoryGraph 是一个面向 AI 智能体信念的“本地优先”证据与修订层。它保留原始观测、把声明表示为时序图，并解释某条声明为何是当前的、历史的或存在争议的。

MVP 状态

确定性 MVP 正在运行。权威架构始于 00-architecture-index.md；已实现的内核覆盖：

• 不可变的源观测。

• 带类型实体节点与拥有精确证据区间的原子声明边。

• 双时态的当前与历史信念查询。

• 显式的确认、反驳和原子级取代。

• recall、history 与 explain 命令。

• 硬性 bank 隔离，以及只追加的变更事件日志。

• 一个与 Provider 无关的 Dream 提案校验器，包含证据、水印、声明版本、幂等性、置信度、质疑者与评审门控。

• 可持久化的 Dream 运行、任务、提案、审查项、租约、事件水印与原子提案提交。

• 一个确定性的元数据 Provider，可在不向外部模型发送源数据的情况下走完整个 Dream 循环。

• MemoryRotBench 固定夹具、基线、检索评分与引擎集成。

• 混合 FTS/vector 召回，带无依赖的本地基线与可替换的嵌入器。

• 针对不可信指令类内容的检索时隔离。

• 可崩溃恢复、支持租约、心跳续期、重试与可安全续跑的 Dream worker。

• 一个 OpenAI 兼容的结构化输出 Provider，只允许提出候选方案。

• 一个五工具 STDIO MCP 服务器：recall、record、explain、correct 与 forget。

• 用户批准的 Codex JSONL 摄取，以及作用域的项目 Codex 安装器。

• 一个确定性的、兼容 Obsidian 的 Markdown 评审投影。

• 对成功与失败编码尝试进行有界复用的一等公民“procedural episodes”。

• 可复现的无记忆、Markdown、BM25、扁平上下文以及三类/Graphify 的基准适配器。

• 跨平台 CI、包验证，以及可执行的 doctor 诊断。

真实引擎目前 12/12 通过全部公开 MemoryRotBench 查询，并通过全部七个生产 chaos contracts（生产混沌契约）。在本文档对应的检查点上，仓库测试套件共有 196 个通过。在首个带指纹的公开矩阵中，最强的简单基线通过 7/12，而 MemoryGraph 通过 12/12。

快速开始

uv sync
uv run memorygraph init --database /tmp/memorygraph.db
uv run memorygraph doctor --database /tmp/memorygraph.db
uv run memorygraph bank create personal:founder --database /tmp/memorygraph.db
uv run memorygraph dogfood bootstrap --database /tmp/memorygraph.db
uv run memorygraph predicate define works_at \
  --bank personal:founder --cardinality one --volatility volatile \
  --database /tmp/memorygraph.db

记录证据，然后把它转成一条声明：

OBSERVATION_ID=$(uv run memorygraph observe "Abrar works at Acme." \
  --bank personal:founder --source-key event:acme \
  --database /tmp/memorygraph.db)

CLAIM_ID=$(uv run memorygraph claim assert Abrar works_at Acme \
  --bank personal:founder --observation "$OBSERVATION_ID" \
  --database /tmp/memorygraph.db)

Python API 还为嵌入式应用暴露了 confirm_claim、contradict_claim、supersede_claim、recall、history 与 explain。

记录一次编码尝试，让后续智能体可以复用成功的策略——或避开已知的失败——而不必假装它普遍正确：

memorygraph record-attempt "Run migrations before starting the worker" \
  --bank project:my-app --source-key attempt:migrate-worker \
  --task "start durable worker" --outcome success \
  --applicability-json '{"database":"sqlite"}'

运行 Dream 循环

嵌入式 Provider 从 metadata.memorygraph 读取带类型的候选，提出图变更，验证证据与时间前置条件，然后在一个事务中提交所有符合条件的提案。模型型 Provider 采用相同的“仅候选”协议，永远不会拥有直接的数据库写路径。

PYTHONPATH=src:. uv run python examples/run_dream_cycle.py \
  --database /tmp/memorygraph-dream.db

uv run memorygraph dream status RUN_ID \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream reviews \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream rollback RUN_ID \
  --bank personal:founder --database /tmp/memorygraph-dream.db

对于 CLI 摄取，用 observe --metadata-file FILE.json 传入候选包，再运行 memorygraph dream run --bank BANK。--mode dry_run 会验证并持久化提案，但不会使用本次观测，也不会更改声明。

对于持久化执行，先把工作排队，再单独运行 worker：

uv run memorygraph dream queue \
  --bank personal:founder --database /tmp/memorygraph-dream.db

uv run memorygraph dream worker \
  --bank personal:founder --database /tmp/memorygraph-dream.db

若要使用 OpenAI 兼容的 Responses 端点，请设置已配置的密钥变量，并把模型同时传给队列和 worker。Provider 的输出会被解析为严格的结构化数据，并仍然通过相同的确定性证据和提交门控。

export OPENAI_API_KEY=...
uv run memorygraph dream queue --bank personal:founder \
  --provider-model YOUR_MODEL --database /tmp/memorygraph-dream.db
uv run memorygraph dream worker --bank personal:founder \
  --provider-model YOUR_MODEL --database /tmp/memorygraph-dream.db

接入 Codex

安装包、初始化一个项目 bank，并加入项目级 MCP 配置：

uv run memorygraph init
uv run memorygraph bank create project:my-app
uv run memorygraph install-codex --project .
uv run memorygraph probe-codex --project .

安装器会创建或修复 .codex/config.toml 中的 [mcp_servers.memorygraph] 区块，将其指向当前 Python 环境中的 memorygraph.mcp STDIO 模块，并把 Codex 配置成每次写入前提示。它不会改动全局 Codex 配置。这五个 MCP 操作都需要显式的 bank 范围。

probe-codex 会验证项目配置，并演练一条真实的 MCP 子进程生命周期。若想探测配置好的项目数据库，而不是创建一次性可丢弃的探测库，则请使用 --project-database。

导入会话内容属于可选项。每条 JSONL 记录必须带有 bank、session_id、turn_id、role、content 和 approved；默认会跳过未获批的记录：

memorygraph ingest-codex approved-session.jsonl

Dogfood Alpha

官方离线六臂（six-arm）夹具矩阵为：

PYTHONPATH=src:. uv run python examples/run_dogfood_fixture_matrix.py

若用于真实项目，请先启动运行契约上的操作流程：

uv run memorygraph dogfood bootstrap \
  --database .memorygraph/memory.db \
  --bank project:my-app \
  --workspace my-app

该夹具矩阵会运行以下臂：

• no_memory

• markdown

• memorygraph_graph_only

• memorygraph_gated_dream

• memorygraph_always_dream

• graphify_compatible

它测量任务通过与失败、有效召回精确率、禁用或过期召回泄漏、重复错误、延迟、Token 估算、工具调用、重试、预期成本字段以及 Dream 评审负载。结果写入 benchmarks/reports/dogfood-offline-mvp.json 和追加为主的账本 benchmarks/reports/dogfood-offline-mvp.jsonl。 任务通过/失败遵循查询期望；Dream 评审积压仍作为单独可见的成本来记账。

当前离线夹具结果（2026-08-22）：

• memorygraph_always_dream: 3/3

• memorygraph_graph_only: 1/3

• memorygraph_gated_dream: 1/3

• graphify_compatible: 1/3

• markdown: 1/3，并出现禁止片段泄漏

graphify_compatible 是一个协议适配器，它让外部检索器在同一清单、相同时间边界与相同评分契约下参与比拼。它并不表示本仓库已经完成过一次真实的 Graphify 对比。

在 Obsidian 中进行人工评审

生成一个包含当前声明、精确来源、relations（关系）以及 Dream 评审队列的 Markdown vault：

memorygraph project-obsidian --bank project:my-app \
  --output .memorygraph/obsidian

这段 Markdown 是可忽略的，由清单管理。SQLite 观测和 append-only 事件保持事实源不变；对生成笔记的修改永远不会静默改写记忆。

为什么选择图？

图给智能体带来可组合的结构：实体是节点，像 Abrar --works_at--> Stripe 这样的主张则是带类型的边。MemoryGraph 并不把一条边当作永恒真理。每种声明版本都携带有效时间、系统时间、生命周期、来源与精确证据片段——这才是可用的记忆图与冗旧事实库之间的差别。

开发

uv sync --extra dev
uv run pytest
uv run ruff check .
PYTHONPATH=src:. python examples/run_memoryrotbench_memorygraph.py
PYTHONPATH=src:. python examples/run_memoryrotbench_chaos_memorygraph.py
python examples/run_memoryrotbench_baseline_matrix.py
PYTHONPATH=src:. uv run python examples/run_dogfood_fixture_matrix.py

预期结果：12/12 公开检索用例，以及 7/7 生产 chaos 用例。该矩阵会把不可变的、带语料与评估器指纹的记录追加到 benchmarks/reports/public-baseline-matrix.jsonl。提供 --graphify-command，即可用完全相同的可见语料与评分契约运行外部的 Graphify 适配器。

下一个产品层

下一个门槛仍然是真实场景验证：有真实模型支撑的“实勤 dogfood”会话、真正的 Graphify 正面对比，以及在真实编码工作上的设计交付。全流程删除残留都会被审计并报告；任何无法在不重写历史的前提下被安全清除的身份残留，都会被显式安全地 sec 暴露出来，而不是隐藏。Dream 验证器仍然是每个 provider 和 worker 都必须经过的安全隘口。

采用 Apache-2.0 许可发布。