内容
<p align="center">
<img src="assets/retconary-banner.svg" alt="Retconary — 本地AI智能体内存防火墙" width="100%" />
</p>
<p align="center">
<strong>阻止AI智能体根据过时的记忆采取行动 — 在本地，提供来源证明。</strong>
</p>
<p align="center">
<a href="https://youtu.be/hTR6fnouXtU">观看2:44演示视频</a> ·
<a href="#查看核心证明">核心证明</a> ·
<a href="#本地运行">本地运行</a> ·
<a href="#连接AI智能体">连接智能体</a> ·
<a href="docs/ARCHITECTURE.md">架构</a>
</p>
## Retconary 一分钟了解
Supermemory 可以检索最语义相关的记忆。但相关性并不保证记忆在 AI 智能体即将采取行动时仍然有效。
Retconary 在**记忆回忆**和**智能体行动**之间添加了一个本地验证门。它检查召回的陈述是否与已审查的时间证据账本相符，并返回四种裁决之一：
- `当前` — 支持且安全可使用。
- `过时` — 以前正确，但已被新证据取代。
- `冲突` — 未解决的证据需要人工审查。
- `不支持` — 没有审查的来源支持该陈述。
每个裁决都包括原始来源、有效性边界、因果历史和安全当前上下文（如果存在替换）。
## 它阻止的失败
包含的演示记录了两个实际决策：
1. **Atlas 被选中**用于仓库操作。
2. 稍后审查的消息 **替换 Atlas 为 Nova**。
然后要求智能体继续使用 Atlas。由于任务明确命名了 Atlas，因此它可以保持为 Supermemory Local 返回的最高语义结果。Retconary 不会丢弃该检索结果；它会在执行前进行验证。
```text
Supermemory 回忆 Atlas — 高度相关
时间证据 Atlas 被 Nova 取代
Retconary 裁决 过时 → 阻止
安全当前上下文 Nova 是选定的机器人
智能体结果 在执行前纠正
```
这就是产品：**Supermemory 记得什么是相关的；Retconary 检查是否仍然安全执行。**
## 观看演示
<p align="center">
<a href="https://youtu.be/hTR6fnouXtU">
<img src="https://img.youtube.com/vi/hTR6fnouXtU/maxresdefault.jpg" alt="观看 2:44 Retconary 演示" width="88%" />
</a>
</p>
2:44 演示展示了一个真实的本地智能体通过 Supermemory 检索 Atlas，起草不安全的行动，接收 `过时` 裁决，跟随审查的替换为 Nova，并在执行前纠正自己。
## 为什么 Supermemory Local 很重要
Supermemory Local 是语义记忆引擎，不仅仅是装饰性的集成。
- 每个来源都在特定的 Supermemory 容器中索引。
- 守护检查搜索 Supermemory 以获取与提议行动相关的证据。
- 智能体实时运行使用最高排名的回忆记忆来起草其初始行动。
- Retconary 将这些语义匹配附加到最终证明，同时其审查的账本决定时间有效性。
- 失败的同步保持可见并可以重试，当本地引擎返回时。
这种分离是有意的：
```text
语义相关性 → Supermemory Local
时间有效性 → Retconary 证据账本
执行许可 → Retconary 记忆守护
```
语义相似性可以发现证据，但它不能无声地将未经审查的陈述提升为当前决策。
## 查看核心证明
使用 Retconary、Supermemory Local 和 Ollama：
1. 打开 `http://127.0.0.1:4317`。
2. 输入 **机器人选择 — 记忆收件箱演示**。
3. 打开 **智能体**。
4. 保留准备好的 Atlas 任务不变，点击 **运行保护的智能体**。
5. 观察实时跟踪执行：`回忆 → 起草 → 验证 → 阻止 → 替换 → 纠正`。
6. 暂停在 **智能体在执行前纠正** 并检查 Atlas → Nova 证明。
7. 加载安全的当前场景并再次运行，查看 Nova 通过为 `当前`。
跟踪由实际的本地调用生成。UI 流式传输 Supermemory 回忆、Ollama 输出、守护验证、替换查找和纠正的智能体响应。
如果 Ollama 不可用，打开 **记忆守护** 并验证：
```text
继续使用 Atlas 进行仓库操作。
```
确定性守护仍然返回相同的过期裁决、Nova 替换和来源线索，而不假装模型调用发生。
## 还可以验证什么
| 界面 | 验证内容 |
| --- | --- |
| **记忆收件箱** | 对话成为可编辑的决策候选。预览执行零写入；只有批准的候选进入账本。 |
| **记忆守护** | 提议的答案或行动在执行前分类，并获得安全的替换上下文，当过期时。 |
| **证据 X 光** | 原始措辞、来源指纹、有效性间隔和因果替换保持可检查。 |
| **时间机器** | 问题可以从有效时间戳的状态中回答，而无需重写历史。 |
| **矛盾雷达** | 未解决的证据被浮现以供审查，而不是被无声地解决。 |
| **反事实实验室** | 可以在不改变记录现实的情况下探索假设分支。 |
| **MCP 服务器** | 外部 AI 客户端可以在执行前执行相同的只读验证。 |
| **本地预检** | 接口公开 Retconary、账本、Supermemory Local 和 Ollama 是否实际准备就绪。 |
## 它是如何工作的
```text
浏览器 UI AI 客户端 / 编码智能体
| |
| Retconary MCP（stdio）
+--------------------+-------------------+
v
Node.js API 在 127.0.0.1:4317
|
记忆守护
+-----------+------------+
v v
SQLite 时间账本 Supermemory Local
有效性 + 来源 语义回忆
+-----------+------------+
v
裁决 + 来源证明 + 安全上下文
可选本地推理：localhost:11434 上的 Ollama
```
Retconary 在解释之前记录证据。SQLite 保存不可变的来源、审查的声明、有效性间隔和因果链接。Supermemory Local 索引和检索相关证据。Ollama 可以协助提取、比较和可执行的智能体循环，但可选的模型输出永远不会成为无形的真相来源。
有关数据模型和信任边界，请阅读 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 本地运行
### 要求
- Node.js 24 或更新版本
- Supermemory Local
- Ollama 配合 `qwen2.5-coder:7b` 以完成完整的 Agent Live Run
### 1. 安装 Retconary
```powershell
npm.cmd install
```
### 2. 启动 Supermemory Local
在项目目录中运行本地内存服务器：
```bash
npx supermemory local --port 6767
```
在 Windows 上，如果安装程序无法启动 Linux 服务器二进制文件，请从 WSL 启动已安装的二进制文件：
```bash
cd /mnt/c/path/to/retconary
PORT=6767 ~/.supermemory/bin/supermemory-server
```
完成首次运行的提供者和嵌入提示。Retconary 默认目标为 `http://localhost:6767`。
### 3. 启动可选的本地推理
```powershell
ollama pull qwen2.5-coder:7b
ollama serve
```
### 4. 启动 Retconary
```powershell
npm.cmd run start
```
打开 [http://127.0.0.1:4317](http://127.0.0.1:4317)。
仅当覆盖端点、Ollama 模型、SQLite 路径或本地身份验证时，请复制 `.env.example` 到 `.env`。`.env`、本地数据库、模型数据和渲染的媒体被 Git 忽略。
### 恢复确定性演示
```powershell
npm.cmd run demo:reset
```
这仅重置内部标记的演示装置，并保留其他所有本地案例。一旦 Supermemory Local 准备就绪，请在界面中使用 **同步** 来索引任何恢复的待处理来源。
## 连接 AI 智能体
Retconary 包括通过 stdio 的 MCP 服务器。保持 Retconary 应用程序运行，然后使用以下配置的 MCP 兼容客户端：
```json
{
"mcpServers": {
"retconary": {
"command": "node",
"args": ["C:/absolute/path/to/retconary/apps/mcp/src/index.js"],
"env": {
"RETCONARY_API_URL": "http://127.0.0.1:4317"
}
}
}
}
```
服务器公开五个只读工具：
- `retconary_list_cases`
- `retconary_verify`
- `retconary_current`
- `retconary_at_time`
- `retconary_evidence`
预期的智能体策略很简单：在采取回忆的决策之前调用 `retconary_verify`；阻止 `过时`，并请求审查 `冲突` 或 `不支持` 结果。
## 验证
```powershell
npm.cmd run verify
```
测试套件验证：
- 过时的回忆在智能体执行前被阻止和替换；
- 当前的来源支持的记忆被允许；
- 语义相似性不能覆盖时间真相；
- 未解决的转换暂停审查；
- 账本在重启后存活；
- 待处理的 Supermemory 事件在恢复后同步；
- 五个 MCP 工具可发现。
当前状态：**9 项测试通过**。
## 隐私和信任边界
- Retconary 服务器仅绑定到 `127.0.0.1`。
- 案例数据存在于被忽略的 `.retconary/` 目录下。
- 导入的文档提取在本地运行。
- 默认内存和推理端点目标为 localhost。
- MCP 工具是只读的，不能批准或替换证据。
- 记忆收件箱预览永远不会写入账本。
- 反事实分支永远不会改变记录的现实。
- SQLite 是本地的，但 Retconary 不加密；当需要静止加密时，请使用操作系统或全磁盘加密。
## 当前范围和路线图
Retconary 当前接受粘贴的对话和导入的 TXT、Markdown、JSON 和 PDF 文档。摄取仍然是刻意的：人员审查提取的内容，然后任何候选才能更改记录的记忆。
未来版本可以添加可选的直接连接器，用于 Slack、Discord、会议记录和 AI 聊天平台。这些连接器应馈送相同的审查优先管道，同时保留消息级来源和明确批准。
## 仓库地图
```text
apps/web/ 交互式调查和演示界面
apps/server/ 回路 API、账本、守护、Supermemory 和 Ollama 适配器
apps/mcp/ 用于外部智能体的只读 MCP 工具
assets/ 品牌和产品实际截图
scripts/ 安全的确定性演示重置
tests/ 隔离的智能体、守护、持久性和 MCP 验证
docs/ 技术架构和本地项目记录
```
## 许可证
[MIT](LICENSE) © 2026 xFurti
