内容
# 上下文账本
**人工智能记忆的 Git。**
遵循 GPL-3.0 许可。Python 3.11+。93 个测试通过。包含命令行接口、REST API 和 MCP 服务器。
[](https://github.com/MohamedHussien-zseeker/ContextLedger/actions/workflows/tests.yml)
[](https://github.com/MohamedHussien-zseeker/ContextLedger/actions/workflows/codeql.yml)
[](https://github.com/MohamedHussien-zseeker/ContextLedger/actions/workflows/lint.yml)
为人工智能代理提供本地优先、可人工编辑的记忆基础设施。可搜索、可检查、可版本控制的项目知识，跨会话和助手存续。
> 上下文账本是 [AI 记忆操作系统](docs/architecture.md) 架构的实现。
*您刚刚看到的：初始化保险库，捕获源，处理成链接知识，索引到 SQLite，搜索 BM25 分数，检查图健康，诊断问题 — 7 个命令，30 秒，零云。*
## 快速安装
```bash
git clone https://github.com/MohamedHussien-zseeker/ContextLedger.git
cd ContextLedger
./install.sh
```
**Termux（安卓）：** 首先安装构建所需，然后参阅 [docs/quickstart.md](docs/quickstart.md#termux-android) 获取完整说明：
```bash
pkg install git python rust clang make pkg-config openssl libffi
```
## 30 秒演示
```bash
memory init ~/my-vault
memory --vault ~/my-vault capture file my-notes.md
memory --vault ~/my-vault process
memory --vault ~/my-vault index --apply
memory --vault ~/my-vault search "your query"
memory --vault ~/my-vault health
memory --vault ~/my-vault doctor
```
## 为什么使用上下文账本
人工智能会话在压缩后会丢失上下文。项目决策分散在聊天、笔记和终端中。代理检索上下文而不解释其来源。
**问题：**
- 会话在压缩后忘记项目状态
- 文档与实际部署的内容不符
- 代理无法解释为什么检索特定的上下文
- 记忆锁定在专有格式或云服务中
**上下文账本通过简单的循环解决这个问题：** **捕获 → 处理 → 链接 → 索引 → 搜索 → 服务**。记忆以 Markdown 形式存在，您可以编辑，索引在 SQLite 中以实现快速搜索，并通过命令行接口、REST 或 MCP 为任何代理使用。
不是代理 — 代理使用的记忆层。
## 当前版本
**v0.1.2** — 首次工作版本。
| 功能 | 状态 |
|------------|--------|
| 保险库初始化 | 工作中 |
| 源捕获（文件） | 工作中 |
| 处理管道 | 工作中 |
| 知识图（维基链接，MOC） | 工作中 |
| SQLite + FTS5 索引 | 工作中 |
| BM25 搜索与分数 | 工作中 |
| 图健康指标 | 工作中 |
| REST API（FastAPI） | 工作中 |
| MCP 服务器（stdio） | 工作中 |
| 93 个测试通过 | 已验证 |
**下一步：** v0.2 添加 Git 支持的记忆历史和漂移检查。
## 集成界面
上下文账本提供四种访问记忆的方式：
| 接口 | 适用于 | 协议 |
|-----------|-----|----------|
| **命令行接口** | 人类，脚本 | `memory` 命令 |
| **REST API** | 应用，网关 | HTTP，绑定到 localhost (`127.0.0.1:9314`) |
| **MCP 服务器** | 人工智能代理 | stdio JSON-RPC |
| **Markdown 保险库** | Obsidian，手动编辑 | 磁盘上的文件 |
| **上下文桥** | 移动 AI 应用 | 通过 `cl-context` 的剪贴板复制/粘贴 |
任何支持 MCP 或 HTTP 的代理都可以使用上下文账本作为其记忆层。移动 AI 应用可以使用上下文桥将检索到的记忆粘贴到 Gemini、ChatGPT、Claude 或任何其他聊天应用中。
## 功能
- **人类可编辑的记忆** — 您可以检查、编辑和版本控制的 Markdown 文件
- **知识图** — 具有 SQLite 关系跟踪的维基链接和中心 MOC
- **BM25 全文搜索** — 具有相关性评分的 SQLite FTS5
- **提供者系统** — 可扩展的捕获（文件提供者，自定义源）
- **图健康指标** — 连接性，隔离的笔记，组件分析
- **REST API** — 默认绑定到 localhost 的 FastAPI 服务器 (`127.0.0.1:9314`)
- **MCP 服务器** — 用于 AI 代理集成的 stdio JSON-RPC
- **上下文桥** — 用于移动 AI 应用的剪贴板集成 (`cl-context`)
- **可选 Qdrant** — 通过向量嵌入实现语义搜索
## 命令行接口命令
| 命令 | 描述 |
|---------|-------------|
| `memory init [path]` | 创建一个新的保险库 |
| `memory capture <scheme> <target>` | 通过提供者捕获源 |
| `memory process` | 将原始源处理成知识笔记 |
| `memory index --apply` | 将保险库索引到 SQLite |
| `memory search "query"` | 带有 BM25 分数的全文搜索 |
| `memory health` | 图连接报告 |
| `memory doctor` | 诊断保险库问题 |
| `memory serve` | 启动 REST API 服务器 |
| `memory mcp` | 启动 MCP stdio 服务器 |
| `cl-context "query"` | 搜索并将上下文复制到 AI 应用的剪贴板中 |
## 架构
```
知识源 → 处理管道 → 人类可编辑的记忆 → SQLite → 搜索/API/MCP → 代理
```
保险库结构：
```
vault/
├── raw/ # 捕获的源
├── wiki/
│ ├── generated/ # 自动生成的知识笔记
│ └── hubs/ # 主题中心 MOC
├── data/memory.db # SQLite 数据库
└── _index.md # 保险库根
```
## 路线图
| 版本 | 焦点 | 状态 |
|---------|-------|--------|
| **v0.1.2** | 核心循环：捕获、处理、索引、搜索、服务 | 已发布 |
| **v0.2** | Git 支持的记忆历史和漂移检查 | 计划中 |
| **v0.3** | 检索可解释性和出处 | 计划中 |
每个版本都包括测试、演示更新和文档更新。
## 比较
| 功能 | 上下文账本 | Obsidian | Vector DB | 代理框架 |
|---------|:---:|:---:|:---:|:---:|
| 人类可编辑的记忆 | 是 | 是 | 否 | 取决于 |
| 知识图 | 是 | 是 | 否 | 取决于 |
| 代理就绪 API/MCP | 是 | 否 | 部分 | 是 |
| 多个代理共享 | 代理就绪（MCP/API） | 否 | 部分 | 部分 |
| 可选语义搜索 | 是 | 否 | 是 | 取决于 |
| 本地优先 | 是 | 是 | 取决于 | 取决于 |
## 测试
```bash
pytest -q
```
93 个测试覆盖命令行接口、API、MCP、搜索、图、处理器和集成。
## 文档
- [快速入门](docs/quickstart.md) — 分步指南
- [架构](docs/architecture.md) — 系统设计和数据模型
- [API 参考](docs/api.md) — REST 端点文档
- [贡献](CONTRIBUTING.md) — 开发设置和指南
## 要求
- Python 3.11+
- 带有 FTS5 支持的 SQLite（包含在 Python 的 sqlite3 模块中）
## 许可
GPL-3.0
