内容
# Facto
[](https://github.com/giorgiocreazione-web/facto/blob/main/LICENSE)
[](https://www.python.org/downloads/)
[](#local-by-design)
[](https://github.com/giorgiocreazione-web/facto/actions/workflows/smoke.yml)
[](https://github.com/giorgiocreazione-web/facto/actions/workflows/smoke.yml)
**每个记忆工具都会记住。 Facto 知道自己何时出错。**
为使用 AI 代理构建项目的人们提供本地引擎 —— **已过时事实**，知道当前**什么是真实的**，**检查自己是否与 git 仓库一致**，并自动为每个代理会话提供信息 —— Claude Code、Cursor、Copilot、Codex、Gemini 或您接下来使用的任何工具。
## 快速开始
```bash
uv tool install facto-memory # 或：pipx install facto-memory / pip install facto-memory
```
没有 `uv`？一行命令即可安装所有内容，甚至在没有 Python 的机器上：
**macOS · Linux**
```bash
curl -LsSf https://raw.githubusercontent.com/giorgiocreazione-web/facto/main/install.sh | sh
```
**Windows** （PowerShell）
```powershell
irm https://raw.githubusercontent.com/giorgiocreazione-web/facto/main/install.ps1 | iex
```
然后连接您的项目：
```bash
cd your-project
facto connect --all # Claude Code 钩子 + MCP + git + AGENTS.md — 以及它检测到的任何编辑器
facto dashboard # Mission Control 在您的浏览器中自动打开
```
现在，在同一文件夹中打开您的代理（`claude`、`cursor` 等）。在第一次运行中，它会接收引导设置播放书，探索项目，**为您建议区域**，并在您确认后建立记忆 —— 没有盲目自动检测。
从那时起，每个会话都会带有您的简报（目标、当前状态、障碍、最后的交接），并且代理通过 MCP 读取和写入记忆。 如果引擎出现故障，会话会被告知它是从头开始的 —— 没有静默失败。
需要 git。离线可用。运行 `facto --help` 获取所有信息。
*（如果 `facto` 命令未找到，请使用 `python -m facto …`）*
## 为什么需要信任灯
每个记忆工具都可以告诉您它存储了什么。 但没有一个工具可以告诉您**是否相信它** —— 过时的记忆比没有记忆更糟糕，因为您的代理会自信地按照它运行。
Facto 会将其记住的内容与 git 仓库的实际状态进行比较，并在每次启动时大声说出来：
```
================ TRUST LIGHT ================ (2026-07-24 19:28)
[GREEN ] ENGINE · 对齐
[YELLOW] UI · 记忆落后 2 次提交 - 请检查 git 状态
[RED ] CONTENT · 无状态记录，可能有 4 个事实已过时
----
GLOBAL: RED （GREEN=信任 · YELLOW=验证 · RED=刷新/不信任）
```
一种可以说“不信任我”的记忆才是您可以信任的。
## 它是如何工作的
```mermaid
flowchart LR
A["您的 AI 代理<br/>Claude Code · Cursor · Codex · Gemini · …"]
subgraph P["您的项目 — 100% 本地，无网络调用"]
direction LR
E["Facto 引擎<br/>已过时事实，时间双向"]
DB[(".facto/facto.db<br/>SQLite, WAL")]
G["您的 git 仓库"]
T{{"TRUST LIGHT<br/>绿色 · 黄色 · 红色"}}
E --> DB
DB --> T
G -->|"每次启动时比较"| T
end
A -->|"通过 MCP 写入事实<br/>决策发生时"| E
T -->|"会话开始时注入简报"| A
DB --> M["Mission Control<br/>浏览器中的仪表盘"]
```
- **事实，而不是聊天。** 短小、注明日期、类型化的条目 —— *“决定：Tailwind v4，拒绝 Bootstrap - 2026-06-19”*。一千个事实在毫秒内保持可搜索。
- **时间双向。** 一个新事实 *关闭* 旧事实，而不是覆盖它：当前图片保持干净，历史保持可查询。您可以随时询问 *我们在五月相信了什么，为什么它改变了？*
- **区域，而不是一个大 blob。** 记忆按区域划分（引擎、ui、内容...），因此每个代理都获得其所在角落的指南针。
- <a id="local-by-design"></a>**本地设计。** 项目内只有一个 SQLite 文件。纯 Python 标准库 —— **零依赖，无账户，无遥测**。引擎不进行网络调用，代码在这里供您检查。
## 您前 10 分钟
一个全新的项目上的实际演练 —— 以下每个输出都是实际命令输出。
**1 · 连接项目** （一次）
```console
$ cd starforge && facto connect --all
准备 facto.config.json（为空 — 代理在第一次运行时设计区域）
连接（claude-code）：
[ OK ] claude-code：钩子添加到 .claude\settings.json
下一步 — 在此文件夹中打开您的 AI 代理（claude，cursor，...）：
它获取设置播放书，探索项目，建议区域，
并在您确认后建立记忆。您也可以手动操作吗？`facto add-area <slug> <path>`
```
**2 · 打开您的代理 — 或手动构建记忆。** 代理在第一次运行期间建议区域；您自己做需要两个命令：
```console
$ facto add-area engine engine --label "引擎 (ECS)"
✓ 区域 'engine' 已添加 -> engine [1 个区域（s）总计]
$ facto add engine decisione "ECS 优于继承 - 配置文件 4 倍更快，10k 小行星"
+ [engine/decisione] 有效期=2026-07-24 -> 指南针： «决策 / 约束»
```
**3 · 询问灯光是否可以信任记忆：**
```console
$ facto status
================ TRUST LIGHT ================ (2026-07-24 19:28)
[YELLOW] ENGINE · 状态尚未锚定到 git — 运行 `facto ingest-git`
...
```
它甚至告诉您如何修复它：
```console
$ facto ingest-git
引擎：2026-07-24 05547a8 [master] （更新）
ingest-git：完成。
$ facto status
[GREEN ] ENGINE · 对齐
```
**4 · 用交接棒结束会话：**
```console
$ facto handoff engine
交接保存 [engine] （新，171 个字符）
```
**5 · 明天，简报自动开启会话** — 这是您的代理（和 `facto brief engine`）在编写一行代码之前会看到的内容：
```console
================ ENGINE ================ （2026-07-24 19:29 状态）
真实 GIT > 活动分支：master
-------- 我们现在的位置 --------
- 空间哈希已登陆：10k 实体在 min-spec 笔记本电脑上达到 62 fps
-------- 上次交接 — 会话结束的交接棒 --------
- 垂直切片正在进行中。下一步：导航网格重构（游戏玩法），然后将挖掘层连接到 HUD 热度计。注意：碰撞修复仍然需要其回归测试在 CI 中。
-------- 决策 / 约束 --------
- ECS 优于继承用于实体 - 配置文件 4 倍更快，10k 小行星
```
零重复解释。每个会话都比前一个更进一步。
## 仪表盘
`facto dashboard` 在本地提供 **Mission Control**。反应堆回答唯一重要的问题 —— *我现在可以信任这个记忆吗？* —— 然后显示您在哪里，您的下一步是什么，以及阻碍因素。它用您的代理编写的事实填充自己，并在您工作时实时更新。
当您不想打开终端时，**Compose** 直接在浏览器中编写事实，交接，关闭和区域：
此外，还有每个事实的图表（按区域或类型筛选），全文搜索，每个区域的指南针和统计数据。英语和意大利语。专业视图以诚实的卡片形式出现，从不作为陷阱。
## 与您的技术栈配合使用
一个记忆库，多个代理 —— 通过开放标准（MCP + AGENTS.md）：
| 代理 | 方式 | 连接方式 |
|---|---|---|
| **Claude Code** | 会话钩子 + `.mcp.json` | `facto connect --all` *(端到端测试)* |
| **Cursor** | `.cursor/mcp.json` + AGENTS.md | `facto connect cursor` |
| **VS Code / Copilot** | `.vscode/mcp.json` (`servers` 键) + AGENTS.md | `facto connect vscode` |
| **OpenAI Codex** （CLI/VS Code/app） | `.codex/config.toml` + AGENTS.md | `facto connect codex` |
| **Gemini CLI** | `.gemini/settings.json` + AGENTS.md | `facto connect gemini` |
| **Grok Build** | 读取 Claude Code 的 MCP 配置 | 已被 `.mcp.json` 覆盖 |
| **Windsurf, Zed, Cline…** | 标准 MCP + AGENTS.md | 指向 `facto mcp-serve` |
| **Anthropic 兼容的硬件** （GLM…） | 在 Claude Code 内运行 (`ANTHROPIC_BASE_URL`) | 不需要额外操作 |
| **其他代理 — 甚至可能不存在的代理** | 通用块 (`command: facto`, `args: [mcp-serve]`) | `facto connect any` |
`connect --all` 连接基础（Claude Code，MCP，git，AGENTS.md），并添加编辑器 **仅当此项目已使用它** — 在您的机器上安装 Cursor 不意味着您想在 *此* 仓库中添加其文件夹。其他建议，但不会强迫。配置 **合并，而不是覆盖** （首先写入 `.bak`），`.facto/` 被添加到您的 `.gitignore` 中，以便数据库保持在您的仓库之外。
**没有 MCP？** 每个步骤都可以在 shell 中执行 — `facto add-area`、`facto add`、`facto handoff`、`facto status` — 这正是 AGENTS.md 块教任何读取它的代理的内容。
*Claude Code 已进行端到端测试。对于每个其他配置，确定性检查 (`mcp_config_check.py`，在 CI 中为 Windows/macOS/Linux 绿色）证明我们编写的文件实际上启动了一个有效的 Facto 服务器 — 包括未知工具的情况。*
## 您的代理获得什么（MCP — 读取 **和** 写入，在免费版中）
`facto_status` · `facto_brief` · `facto_search` · `facto_add_fact` ·
`facto_close_fact` · `facto_handoff` · `facto_add_area` · `facto_remove_area`
*（CRM 三元组 — 实体，任务，关系 — 在专业版中加入）。*
## 每日循环
1. **打开会话** — 钩子注入简报。零重复解释。
2. **工作** — 代理通过 MCP 记录决策，阻碍因素和错误。
3. **关闭** — `facto handoff <area>` （三个有指导的问题）留下交接棒。
4. **`facto status`** — 信任灯告诉您记忆是否跟上。
5. **明天：进一步开始。** 数据库的静默快照在会话开始时拍摄（`.facto/backups`），因此几个月的记忆不会依赖于任何人的纪律。
## 同时使用多个代理
是的 — 而这是一个正常的设置，不是黑客。数据库接受并发读取者，即使有人写入（SQLite 以 WAL 模式），写入时如果发现忙碌会等待其轮次。*已验证，非假设：四个进程同时写入，48 个事实，无丢失。*
两件值得注意的事情：
- **给他们不同的区域。** 事实堆积而不会冲突，但 *状态* 和 *交接* 是每个区域一份：如果两个代理写入同一个区域的交接，最后一个获胜（较早的被关闭成历史，而不是丢失）。
- **需要硬边界？** 使用 `FACTO_AREA=<slug>` 启动代理，如果它尝试写入其他地方 — 包括项目范围内的区域：
```
错误：此代理只能写入 [api]，不能写入 [web]
```
## 您的数据存储在哪里（没有惊喜）
每个事实都写入 `.facto/facto.db` **立即** — 没有保存按钮，没有缓冲，如果会话崩溃则不会丢失。静默快照进入 `.facto/backups` 在会话开始时（最多每 12 小时一个，最后 10 个保留）。它永远不会离开您的机器：没有帐户，没有云，没有遥测 — 而且由于引擎不进行网络调用，您可以在代码中检查而不是相信。
会话 **开始** 时会自动进行 — 打开文件夹中的任何代理都会注入简报。它们 **不会** 自动结束：请在关闭前请求交接，否则下一个会话知道 **什么** 是真实的，但 **在哪里** 您要去。
## 始终在线（可选）
```bash
facto tray on # 登录时启动；在 Windows 上，时钟旁边的图标
facto tray off # 删除它 — 没有任何东西会留下
```
自愿选择，而不是自动的。在 Windows 上，您会看到一个真正的托盘图标：双击打开仪表盘，右键单击为您提供 *打开仪表盘* 和 *退出*。在 macOS 和 Linux 上，仪表盘从登录时直接启动，始终只需一步即可访问。
## 版本
| | **免费** — 此仓库 | **专业版** *(即将推出)* | **最大** *(即将推出)* |
|---|---|---|---|
| 引擎：已过时事实，时间双向历史，信任灯 | ✅ | ✅ | ✅ |
| 完整的 CLI + 会话钩子 + 快照 | ✅ | ✅ | ✅ |
| 完整的 MCP — 读取 **和** 写入 | ✅ | ✅ | ✅ |
| 包括 Compose 的 Mission Control，EN/IT | ✅ | ✅ | ✅ |
| 托盘 / 登录启动 | ✅ | ✅ | ✅ |
| CRM 带有 git 自动导入（实体 · 任务 · 关系） | — | ✅ | ✅ |
| 备份保留，导出，项目模板 | — | ✅ | ✅ |
| 静态存储加密 + 仪表盘访问控制 | — | ✅ | ✅ |
| 浏览器注册向导 | — | ✅ | ✅ |
| **团队通过 git 同步** （无需服务器） | — | — | ✅ |
| **代理舰队编排器** | — | — | ✅ |
| 许可证 | MIT，永久 | 商业 | 商业 |
免费版不是演示版：引擎，CLI，MCP 和仪表盘是完整的，MIT，永久免费。
## 了解更多
- [docs/CONCEPTS.md](https://github.com/giorgiocreazione-web/facto/blob/main/docs/CONCEPTS.md) — 事实，区域，指南针，灯光。
- [docs/SETUP.md](https://github.com/giorgiocreazione-web/facto/blob/main/docs/SETUP.md) — 手动设置，钩子细节，文件夹模式。
- [examples/game-dev](https://github.com/giorgiocreazione-web/facto/tree/main/examples/game-dev) — 一个实际示例配置。
- [CHANGELOG.md](https://github.com/giorgiocreazione-web/facto/blob/main/CHANGELOG.md) — 更改内容，按发布版本。
---
MIT © Giorgio Cristea · 由 [**WCA — Web Creation Agency**](https://wcagency.it) 构建和拥有
