LeoYeAI/talewell

Plugin-first long-term memory for agent platforms — reference implementation of AMP (Agent Memory Protocol).

TL;DR

Talewell 是一个以插件为优先、基于 Git 的 AI 代理长期记忆系统。它将每个记忆记录存储为 Git 仓库中的纯文本 Markdown 文件，为您提供完整的版本历史、差异比对和审计能力，且无需向量数据库。该系统使用简单的 AMP (Agent Memory Protocol)，任何主机（OpenClaw、Claude Code、Codex 等）皆可实现，让代理能根据相关性、时效性和重要性进行确定性的事实回忆。

核心功能

记忆层：一个 Markdown 文件 = 一个记忆记录（事实、实体、情节、程序）。每次写入都会创建一个 Git commit，因此您可以进行回滚、差异比对和变更审计。
协议：AMP 定义了可移植的 JSON 清单 (amp.json) 和固定的磁盘布局 (memory/…)。主机通过六个 MCP 工具 (memory_recall, memory_index, …) 或 CLI 进行交互。
确定性回忆：无需嵌入 (embeddings) 或外部 API 调用。回忆分数是在本地根据“相关性 × 时效性衰减 × 重要性”计算得出。
来源强制验证：仅允许存储用户（拥有者）或代理本身产生的内容。不受信任的来源会被设计机制拒绝。
插件优先：提供 OpenClaw、Claude Code、Codex 的适配器，以及通用的文件惯例备援，让同一个记忆仓库能在不同平台间使用。
链接图谱：记录可以使用 [[id]] 链接互相参照，实现图谱遍历，并产生可注入提示词的精简索引。

适用对象

AI 助手开发者：需要一个可审计、离线优先且适用于任何代理框架的记忆存储系统。
重视数据来源的团队：需要内置机制来阻挡不受信任的写入。
开源 AI 平台维护者（如 OpenClaw、Claude Code）：寻找通用的记忆后端，且不想绑定向量数据库。
研究人员：实验确定性回忆策略，或研究版本化记忆对代理行为影响的学者。

运作方式（概览）

初始化仓库 – talewell init ./my-memory 创建包含 amp.json 和 memory/ 目录的文件夹。
新增记录 – talewell remember --text "Leo 不吃辣" --alias "饮食,辣,diet" --importance 7 写入一个 Markdown 文件 (f-*.md) 并进行 commit。
回忆 – talewell recall "订餐厅要注意什么" 扫描仓库、评分每个事实并返回最佳匹配结果——全程离线。
修正 / 遗忘 – 使用 correct 取代事实（保留历史记录）或使用 forget 移除（Git 中仍保留以供审计）。
图谱与索引 – talewell graph <id> 追踪 [[link]] 参考；talewell index --markdown 建立精简目录，可在每次对话时注入代理的提示词中。
通过 MCP 服务 – talewell serve-mcp 启动服务器并公开六个记忆工具，让任何兼容 MCP 的主机皆可调用。
跨主机传输 – talewell bundle ./transfer.bundle 将仓库打包，以便在不同平台间移动。

待解决问题 / 开放性问题

嵌入层：核心设计刻意避开向量搜索；新增嵌入功能是选配，不属于基准功能。
扩展性：Git 对于中等规模的语料库表现良好，但极大规模的记忆存储库可能会遇到性能瓶颈。
主机生态系：目前仅有少数主机被列为“已验证”；其他主机依赖安全默认值。
安全模型：来源验证机制可阻挡不受信任的写入，但 README 尚未详细说明 MCP 服务器的验证方式。

快速开始 (CLI)

# 1. 创建记忆仓库
talewell init ./talewell-repo

# 2. 记住一个事实
 talewell remember \
   --text "Leo 不吃辣" \
   --alias "饮食,辣,diet" \
   --importance 7

# 3. 回忆某事
 talewell recall "订餐厅要注意什么"

# 4. 为主机提供服务 (例如 OpenClaw)
 talewell serve-mcp

授权

MIT – 可自由使用、修改与重新分发。