Heartwood Memory — governed memory for AI agents

Heartwood Memory — 面向 AI Agent 的受治理记忆

Heartwood Memory 是面向 AI Agent 的受治理记忆存储：具备来源签名审计、策略门控召回、租户隔离，以及擦除时针对每个主体的密钥销毁证明。

许可证一览。 Heartwood Memory 0.2.0 及更高版本依据 Business Source License 1.1（BSL 1.1）以源代码可用形式发布，并非 OSI「开源」许可证。非生产用途不受规模限制，均可免费使用。小型组织——员工和独立承包商少于 100 人，且上一纳税年度收入低于 100 万美元（按许可证规定，以 2019 年为基准调整）——也可免费用于生产。每个版本都会在发布四年后自动转换为 Apache License 2.0。0.1.0–0.1.2 版本采用 MIT 许可证，并永久保留 MIT 许可证。

网站 · 比较 Heartwood · 常见问题 · PyPI

面向 AI Agent、可审计源代码的受治理记忆，可嵌入现有记录系统旁运行。

Heartwood 是 Agent 记忆的加密信任根：每条记忆均经过签名，召回会在排序前执行策略检查，审计日志采用哈希链并可检测篡改，擦除时则会生成可证伪的、针对每个主体的密钥销毁凭据。该软件包以嵌入式 Python 库的形式提供，并包含可在你的基础设施上运行的受治理适配器接口。

明确的边界。 Heartwood 使用托管密钥：服务器会解密数据以提供召回服务。以下凭据目前可通过审查源代码进行审计。删除采用针对每个主体的密钥销毁工作流，并非即时删除保证。请参阅密钥托管与擦除。

安装

python -m pip install "heartwood-memory[recall,mcp]"

开发检查

从源代码检出版本开始，请使用 Python 3.11，并在运行本地质量检查前安装声明的开发依赖项：

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
bash scripts/check.sh

scripts/check.sh 会运行 Ruff 和完整的 pytest 测试套件。除非安装了单独的集成依赖项，否则可选的 Hermes Agent 契约测试套件会报告为已跳过。若要将相同的检查设为 pre-commit 钩子，同时不覆盖其他钩子，请运行 bash scripts/install-hooks.sh。

重新运行公开信任测试套件

公开的信任凭据基准测试位于源代码仓库中，而不包含在已安装的 wheel 中。从干净克隆开始，运行：

git clone https://github.com/jermayne36/heartwood-memory.git
cd heartwood-memory
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --quiet -e ".[dev]"
python bench/run_benchmark.py --out .heartwood/trust-receipt.json

在 Windows PowerShell 中，将激活命令替换为 .\.venv\Scripts\Activate.ps1。

如果可执行契约或正向对照案例失败，或者基准测试现有的声明锚点扫描发现违规，该命令将以非零状态退出。终端中的单行摘要会报告实际案例数量；JSON 文件包含每个探测项的结果，以及单独发布的边界案例。

5 分钟快速入门

记住一条受治理的记忆，在策略约束下召回它，并生成密钥销毁凭据：

from heartwood import Heartwood, Policy, Principal, prove_crypto_erase_path

# 1. Open an embedded, tenant-scoped store.
db = Heartwood(path="./heartwood.db", tenant="tenant:acme")

# 2. Remember. The record is signed and written to a hash-chained audit log.
db.remember(
    "Customer 42 is on the Enterprise plan.",
    subject="customer:42",
    created_by="agent:support",
    policy=Policy(classification="internal"),
)

# 3. Recall. Policy gates the candidate set before ranking.
principal = Principal(
    id="agent:support",
    tenant="tenant:acme",
    roles=("support",),
    clearance="internal",
)
out = db.recall(
    "what plan is customer 42 on?",
    principal=principal,
    filters={"subject": "customer:42"},
    k=5,
)

for hit in out["results"]:
    print(hit["content"], hit["provenance"]["signature_valid"])

# 4. Forget. This crypto-shreds the per-subject key and purges derived artifacts.
receipt = db.forget(
    "customer:42",
    mode="hard",
    actor="agent:support",
    reason="right-to-erasure request",
)
db.close()

proof = prove_crypto_erase_path(
    "./heartwood.db",
    tenant="tenant:acme",
    root_present=False,
).to_dict()
print(receipt["key_shredded"], proof["content_unrecoverable"])

请勿将本地工件提交到 Git。 本仓库的 .gitignore 不会传递到下游仓库。如果你在另一个检出目录中运行这些示例，请在该目录中添加等效的忽略规则，涵盖本地 Heartwood 数据库及其旁置文件、令牌/配置文件、根目录中的 JSONL 输入、生成的 *-report.json 文件和 .venv/；或者，将敏感运行时状态保存在已忽略的 .heartwood/ 目录中。请将有意保留的测试夹具放在非根目录中，以便进行审查。

想为支持 MCP 的 Agent 使用受治理记忆，而不是使用库？请参阅受治理 MCP 快速入门和 Codex 本地 stdio 快速入门。默认不会公开写入和擦除操作；运维人员可选择显式指定这些操作以启用。

你将获得的内容——五种凭证

可在记录级别检查并重新运行的治理机制：

凭证	功能	当前边界
签名溯源信息	每条记忆都有签名；读取时会重新验证签名和内容哈希，并在每条结果中显示验证信息。	默认的 OFF 会显示验证状态；选择 FILTER 会丢弃验证失败的记录，选择 ENFORCE 则会在返回结果前失败。签名范围不包括授权元数据。
防篡改审计	采用哈希链的只追加日志；verify_chain() 可检测原位编辑或行删除。	只要外部 AnchorSink 和固定的验证根仍在攻击者边界之外，就能检测最新锚点及之前的回滚；锚点之后的行仍是明确存在的风险窗口。
排序前执行策略	召回仅限于已获准的记录，然后再进行排序；被拒绝的记录不会参与评分或返回，结果和签名凭证中也都不会包含被拒绝记录的数量。	可通过源代码审计确认其遵循已提交的单信任域预种子策略；不声称支持多租户部署。
密钥销毁凭证	forget(mode="hard") 会销毁每位主体的密钥并清除派生工件。	报告每位主体的密钥销毁情况和清除数量；不证明内容已按字节级别删除。
忠实度与出站门控	生成的记忆只有通过忠实度检查才会被接受；被拒绝的出站请求会阻止对外部模型的调用。	默认会阻止未接受的忠实度结果；store_unaccepted=True 会存储 generated_needs_review 提案，类型化排序会降低其权重。

替换记忆

从 0.2.10 版起，当新记忆注明它所替换的记忆，或通过记忆工具（MCP memory 或 MemoryToolBackend）编辑或删除文件时，Heartwood 的默认召回会停止返回旧文本， 即使重启后也是如此。只有显式请求历史记录时，才能访问已编辑文件的早期版本。

限制。 Heartwood 不会自行检测替换操作：如果写入新记忆时没有注明它所替换的内容，旧记忆和新记忆都会保持当前状态，旧记忆仍可能被召回。

要注明所替换的记忆，请在写入新记忆时传入旧记忆的 ID： db.remember(..., supersedes=old_id)。在 forget() 删除其主体之前，可通过 filters={"include_review_states": ["superseded"]} 访问历史记录。由旧版本写入的记忆工具文件，在下次编辑、重命名或删除之前，其早期版本仍会出现在默认召回中；请参阅 0.2.10 更新日志中的“现有数据”。 详情：召回可见性与退役。

重要文档

• MCP 快速入门
• VS Code + GitHub Copilot MCP
• 轮换连续性演示
• Codex 本地 stdio 快速入门
• 入门指南
• Python API 参考
• 严格模式与审计锚点快速入门
• 签名审计导出与离线验证器
• 密钥托管与擦除
• 多 Agent 身份
• Postgres 与 SQLite 迁移指南
• 完整公开文档索引
• 发布验证与发布流程

安装后运行控制台脚本：

heartwood --help

许可证

从 0.2.0 版本起，Heartwood Memory 根据 Business Source License 1.1（BSL 1.1）采用源代码可见许可——它不是 OSI 定义的“开源”许可。你可以免费阅读源代码、在本地运行、基于它开发、进行评估，并将其用于非生产环境的自托管。小型组织（人数少于 100 人且年收入低于 100 万美元）也可以免费在生产环境中运行。较大型组织需要商业许可证才能用于生产环境。每个版本发布四年后都会自动转为 Apache License 2.0。

0.1.0–0.1.2 版本采用 MIT 许可证，并永久保持该许可。详情请参阅 NOTICE。商业支持、托管密钥保管和托管服务另行提供。

当前侧重

在构建宏大的认知能力之前，先证明基础可信：

• 来源溯源
• 类型化记忆路由
• 感知策略的记忆召回
• 时间状态
• 完整删除
• 生成记忆的忠实度
• 可重复的评测

认知数据库愿景应由这些循环产生的证据来支撑。