内容
<!-- markdownlint-disable MD013 -->
# 全局代理内存
<!-- mcp-name: io.github.ozankasikci/global-agent-memory -->
> 适用于 Claude Code、Codex 等其他与 MCP 兼容的代理的本地优先、项目感知、持久内存。
[](https://www.python.org/downloads/)
[](docs/mcp-contract-v1.md)
[](#security-model)
[](pyproject.toml)
[](https://github.com/ozankasikci/global-agent-memory/releases/latest)
全局代理内存为多个编码代理提供了一个共享的、可审查的内存，而无需将知识库的控制权交给托管服务。Markdown 文件是规范的，经过身份验证的本地 MCP 守护进程是公共代理接口，仪表板允许人类批准、编辑、保护或删除代理记住的内容。
**一个保险库。多个代理。人类控制的内存。**
[快速入门](#quick-start) · [Obsidian 保险库](#obsidian-vault) ·
[仪表板](#dashboard) · [工作原理](#how-it-works) ·
[安全模型](#security-model) · [MCP 合同](#mcp-interface) · [文档](#documentation)
## 为什么是全局代理内存？
编码代理在会话期间很有用，但重要的上下文通常在会话之间丢失或分散在各个客户端。全局代理内存提供了一个持久的知识层，例如：
- 架构决策和项目约定；
- 验证的工作流程和操作手册；
- recurring 问题及其已证实的解决方案；
- 项目偏好、实体和交接摘要；
- 新任务或代理会话的限定上下文。
代理建议记忆为**候选人**。人类在它们成为持久记忆之前审查它们，控制它们的可见性，并且可以稍后更新、替换、存档或硬删除它们。
### 它是如何比较的
| 方法 | 跨代理共享 | 人类可审查 | 项目感知 | 所有者控制的访问 | 可移植的真实来源 |
| --- | :---: | :---: | :---: | :---: | :---: |
| `CLAUDE.md` / `AGENTS.md` | 有限 | ✓ | ✓ | — | ✓ |
| 基本内存 MCP | ✓ | 变化 | 变化 | 变化 | 变化 |
| 主机代理内存 | ✓ | 变化 | ✓ | 提供者定义 | — |
| **全局代理内存** | **✓** | **✓** | **✓** | **✓** | **Markdown** |
使用项目指令文件来编写需要始终包含在提示中的紧凑规则。使用全局代理内存时，知识应可搜索、在客户端之间共享、由人员审查、随时间更新或在显式权限后面隐藏。
## 亮点
- **跨代理共享** — Claude Code、Codex 和其他 MCP 客户端使用相同的服务和不可变的内存 ID。
- **默认项目感知** — Git 根目录、远程、别名和项目注册表将检索范围限定为活动项目。
- **Markdown 是规范的** — 保险库保持可读、可移植、备份友好且与 Obsidian 兼容。
- **人类审查工作流** — 代理创建候选人；所有者批准、编辑、拒绝或解决仪表板中的冲突。
- **受保护和密封的内存** — 敏感知识可以从普通检索中排除，并在所有者控制的访问后面放置。
- **混合本地搜索** — SQLite FTS5 提供关键词检索；可选的 Ollama 嵌入和 `sqlite-vec` 添加语义排名。
- **支持离线** — 当 Ollama 不可用时，关键词搜索和生命周期操作继续。
- **可重建的生成状态** — SQLite、FTS、向量、队列和缓存可以从 Markdown 重建。
- **冻结的 MCP V1 合同** — 工具、资源、提示、信封和兼容性规则在存储库中版本化。
- **本地安全边界** — 守护进程绑定到 `127.0.0.1` 并需要存储在保险库外部的生成的承载令牌。
### 为真实的项目保险库而构建
可选的性能套件创建 **10,000 个合成记忆**，并使用守护进程使用的相同索引和检索路径进行练习。在记录的 macOS ARM64 基线下，完整的重建需要 36.5 秒，暖关键词搜索 P95 为 56 毫秒，暖混合搜索 P95 为 76 毫秒，增量 stdio 代理开销为 1.5 毫秒。结果因机器而异；更改的笔记、搜索和代理预算作为回归门运行。参见[方法和完整的基线](docs/performance-baseline.md)。
## 三个表面，一个内存系统
全局代理内存不仅仅是一个 MCP 服务器。代理、所有者和知识工作者通过三个专门的表面使用相同的规范内存：
| 表面 | 设计用于 | 提供的内容 |
| --- | --- | --- |
| **MCP** | Claude Code、Codex 和其他代理 | 项目感知的上下文、搜索、候选人创建、安全的更新、生命周期操作和通过冻结的 V1 合同的权限请求 |
| **Obsidian 保险库** | 读取、写入、链接和长期知识所有权 | 便携的 Markdown 和 YAML、模板、原生 Bases 视图、项目概览中心、wikilinks、backlinks、图形导航和直接编辑同步 |
| **本地仪表板** | 快速的所有者审查和管理 | 候选人批准和编辑、冲突比较、可见性分类、保护访问决策、搜索、项目、活动、备份和系统健康 |
保险库是持久的真实来源。仪表板是一个互补的控制平面，MCP 接口是代理使用的安全自动化层。你可以使用 Obsidian、仪表板或两者，而无需创建单独的内存副本。
### 仪表板概览
<p align="center"><sub>真实仪表板 UI，带有合成的 Atlas 项目数据。未显示任何私有保险库内容。</sub></p>
## 快速入门
这是 Claude Code、Codex 和其他 MCP 客户端的持久内存的最短路径。引导安装程序创建本地服务、与 Obsidian 兼容的保险库、仪表板、MCP 注册和代理技能。
### 要求
- macOS 或 Linux
- Python 3.12 或更新版本
- [`uv`](https://docs.astral.sh/uv/)
- Claude Code 或 Codex，用于托管客户端集成
- 可选：[Obsidian](https://obsidian.md/) 用于浏览 Markdown 保险库
- 可选：[Ollama](https://ollama.com/) 用于语义检索
### 1. 安装
```shell
uv tool install git+https://github.com/ozankasikci/global-agent-memory.git
```
对于本地检出，请使用 `uv tool install .` 代替。
### 2. 运行引导设置
```shell
global-memory setup
```
设置显示一个计划，并在更改任何内容之前只询问一次。它初始化本地保险库，创建受保护的令牌，安装和启动原生每个用户服务，检测 Claude Code 和 Codex，安装它们的 MCP 集成和技能，验证健康客户端，并打开仪表板。该命令是幂等的，因此再次运行它会修复或更新托管组件，而不会替换无关的客户端配置。
使用标志时，您需要一个非默认设置：
```shell
# 非交互式安装
global-memory setup --yes
# 在首次设置时选择不同的保险库
global-memory setup --vault "$HOME/Memory"
# 仅安装一个客户端，或暂时不安装客户端
global-memory setup --clients claude-code
global-memory setup --clients none
# 预览而不更改文件或服务
global-memory setup --dry-run
```
### 3. 使用安装的代理快捷方式
设置安装了五个基本快捷方式，用于每个检测到的客户端：
| 快捷方式 | 目的 |
| --- | --- |
| `gam-context` | 为任务加载项目感知的上下文 |
| `gam-search` | 查找决策、事实、错误、约定或解决方案 |
| `gam-remember` | 将明确提供的持久知识作为候选人提出 |
| `gam-review` | 显示候选人队列而不更改它 |
| `gam-dashboard` | 打开经过身份验证的仪表板 |
在 Claude Code 中，直接调用它们，例如 `/gam-context fix the upload retry bug`。在 Codex 中，键入 `/skills` 并选择一个，或直接提及它，例如 `$gam-context fix the upload retry bug`。
### 4. 再次打开仪表板
```shell
global-memory dashboard
```
您也可以要求一个连接的代理：
> 打开全局代理内存仪表板。
代理调用 `memory_dashboard_open` 并打开同一个经过身份验证的本地仪表板。
### 手动安装和修复
用于高级设置和故障排除的单独命令仍然可用：
```shell
global-memory init --vault "$HOME/Documents/Global Agent Memory"
global-memory daemon install-service --kind launchd # 在 Linux 上使用 systemd
global-memory integrations install all
global-memory integrations verify all
global-memory doctor
```
## 与代理一起使用
集成后，您通常会描述意图，而不是手动运行内存命令。
### 在工作之前检索上下文
> 在开始之前，加载该项目的相关内存，并总结约定和最近的决策。
### 提出持久的内存
> 记住，生产 ARM64 二进制文件必须在本地构建并上传到服务器。将它作为项目约定与部署讨论作为证据一起添加。
代理创建了一个候选人。在它成为活跃的之前，不会发生任何变化。
### 更新现有的知识
> 找到部署内存并使用新的健康检查命令更新它。不要创建重复的内存。
### 打开审查界面
> 打开内存仪表板，以便我可以审查候选人。
共享的集成技能教导支持的代理何时检索、提出、更新和避免重复内存。
## Obsidian 保险库
配置的 Obsidian 保险库是人类可读的、持久的真实来源 — 不是不透明数据库的导出。每个托管的内存都是一个普通的 Markdown 文件，带有 YAML 属性、稳定的内存 ID、生命周期元数据和项目感知的链接。
初始化添加了一个 Obsidian 工作区，而不会替换现有的文件：
- 用于决策、事实、解决方案、约定、偏好、实体、引用、会话摘要和项目概览的模板；
- 用于候选人审查队列、活动知识、最近更新、按项目划分的决策、已验证的解决方案和生命周期历史的原生 Bases 视图；
- 项目概览中心嵌入项目内存，并在笔记在候选人、活动、拒绝、替换或存档文件夹之间移动时保持稳定；
- wikilinks 和互惠的替换链接，用于 backlinks 和图形导航；
- 观察者同步，以便在 Obsidian 中对普通内容和描述属性的编辑成为可搜索的，而无需重启服务。
Obsidian 是可选的：相同的 Markdown 仍然可读和可编辑，使用任何文本编辑器。生命周期和访问策略更改仍应通过仪表板、MCP 或 CLI 进行，以便验证、乐观并发和审计记录保持完整。
## 仪表板
经过身份验证的仪表板是所有者控制平面，用于：
- 项目概览和最近的项目活动；
- 一次一个候选人的审查和编辑；
- 重复和冲突比较；
- 内存搜索和生命周期管理；
- 标准、保护和密封分类；
- 访问请求批准和活动授予撤销；
- 密封内存所有者解锁，带有审计记录；
- 项目切换、系统健康、重新索引和备份；
- 在 Obsidian 或本地文件查看器中打开规范的 Markdown。
<p align="center"><sub>候选人审查在所有者批准持久内存之前保持证据和冲突可见。</sub></p>
仪表板启动 URL 在 60 秒后过期，只能交换一次，并创建本地 HttpOnly 会话。不要分享启动 URL。
## 内存可见性和访问
| 级别 | 默认代理行为 | 所有者控制 |
| ------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **标准** | 包含在普通的范围检索中 | 正常的候选人和生命周期审查 |
| **保护** | 从默认结果中排除；代理仅接收中立的相关性信号 | 所有者选择确切的内存、权限、持续时间和合格的项目 |
| **密封** | 正文不被索引或通过代理工具返回 | 一个所有者解锁的仪表板视图；每次访问都会审计 |
保护授予按用途、项目、代理、权限、确切的内存 ID 和持续时间限定。所有者可以降级请求，但绝不能提升它。代理可以请求和轮询访问，但它们不能批准、拒绝或撤销授予。
> [!IMPORTANT]
>
> 受保护和密封的内存不是秘密管理器。永远不要在全局代理内存中存储密码、凭证、私钥、API 密钥或承载令牌。
## 工作原理
```mermaid
flowchart LR
A[Claude Code] -->|stdio MCP 代理| D[global-memoryd]
B[Codex] -->|stdio MCP 代理| D
C[其他 MCP 客户端] -->|Streamable HTTP| D
D --> E[应用程序和域服务]
E --> V[Markdown 保险库<br/>规范状态]
E --> I[SQLite FTS5 和 sqlite-vec<br/>生成的状态]
E --> O[Ollama 嵌入<br/>可选]
E --> W[本地仪表板<br/>所有者控制]
```
守护进程是保险库观察器、生成的索引、嵌入队列和 MCP 传输的唯一所有者。Streamable HTTP 客户端直接连接到 localhost；stdio-only 客户端启动薄的 `global-memory-mcp` 代理。两者都公开相同的 MCP V1 合同。
依赖方向是：
```text
传输和客户端适配器 → 应用程序服务 → 域
```
保险库、SQLite、向量、嵌入、Git、Watchdog 和客户端集成是适配器。领域层不依赖于它们。
## MCP 接口
MCP 接口是唯一的 AI 面向的 API。客户端不直接读取保险库、SQLite 数据库、向量、令牌或运行时日志。
冻结的 V1 发现快照当前包含 **17 个工具**、**10 个资源** 和 **6 个提示**。
| 能力 | MCP 工具 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 检索 | `memory_search`, `memory_context`, `memory_get`, `memory_status` |
| 候选人和生命周期 | `memory_remember`, `memory_update`, `memory_approve`, `memory_reject`, `memory_supersede`, `memory_archive` |
| 导航和操作 | `memory_open`, `memory_dashboard_open`, `memory_reindex`, `memory_projects`, `memory_tags` |
| 保护访问 | `memory_access_request`, `memory_access_status` |
所有突变都通过 `request_id` 是可重放安全的。更新使用乐观并发，并且过时的版本会失败并出现 `VERSION_CONFLICT` 错误，而不是静默覆盖更新的知识。
参见 [MCP Contract V1](docs/mcp-contract-v1.md) 和生成的 [`contracts/mcp/v1/`](contracts/mcp/v1/) 架构以获取完整的合同。
## CLI 示例
CLI 使用与连接的代理相同的 MCP 路径；它不会绕过守护进程读取生成的状态。
```shell
# 检查健康状况
global-memory status
global-memory doctor
# 注册并检测项目
global-memory project add my-project --root "$HOME/Projects/my-project"
global-memory project detect "$HOME/Projects/my-project"
# 搜索和构建有界任务上下文
global-memory search "deployment rollback" --project my-project
global-memory context "Prepare the next release" --project my-project --token-budget 3000
# 创建审查候选人
global-memory remember \
"Release rollback procedure" \
"Use the blue-green rollback task and verify both health endpoints." \
--type reference \
--scope project \
--project my-project
# 重建生成的索引
global-memory reindex --full
# 备份规范的 Markdown
global-memory backup "$HOME/Backups/global-agent-memory.zip"
```
运行 `global-memory --help` 或 `global-memory <command> --help` 以获取完整的命令参考。
## 安全模型
全局代理内存设计为本地服务，而不是远程公开的内存 API。
- 守护进程限制为 `127.0.0.1`。
- Streamable HTTP 需要生成的本地承载令牌。
- 令牌、数据库、日志、锁和生成的状态保留在保险库之外。
- 令牌文件使用用户权限。
- 仪表板会话是短暂的、本地的，并且是 HttpOnly 的。
- 路径限定为配置的保险库，并检查遍历和符号链接逃逸。
- 普通日志删除正文、提示、嵌入、秘密和授权材料。
- 生成的状态可以删除并从规范的 Markdown 重建。
- 代理检索对保护和密封的内存是失败关闭的。
请根据 [SECURITY.md](SECURITY.md) 报告安全问题。
## 开发
克隆仓库，然后安装Python和仪表盘依赖：
```shell
uv sync
npm ci --prefix dashboard
```
运行标准质量门：
```shell
make check
```
该门涵盖了Ruff格式化和检查，严格的MyPy，TypeScript生产构建，单元/集成/合约/E2E测试，覆盖率，以及确定性的MCP合约再生。
有用的聚焦命令：
```shell
make unit
make integration
make contract
make e2e
make dashboard-check
make performance # 选择加入10,000-note性能套件
```
更改MCP合约时：
```shell
make contract-generate
make contract-check
```
欢迎贡献。从[CONTRIBUTING.md](CONTRIBUTING.md)开始，保持更改与冻结的V1合约兼容，除非故意引入平行主合约。
## 社区和路线图
- 在[GitHub Discussions](https://github.com/ozankasikci/global-agent-memory/discussions)中提问使用问题和分享代理工作流。
- 从[`good first issue`](https://github.com/ozankasikci/global-agent-memory/labels/good%20first%20issue)或[`help wanted`](https://github.com/ozankasikci/global-agent-memory/labels/help%20wanted)队列中挑选一个范围贡献。
- 在[public roadmap](https://github.com/ozankasikci/global-agent-memory/issues?q=is%3Aissue%20state%3Aopen%20label%3Aroadmap)上关注计划的分布式、安全性和集成工作。
- 如果项目有用，星标仓库可以帮助其他代理工具用户发现它。
## 文档
| 指南 | 目的 |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [操作](docs/operations.md) | 安装、守护进程管理、诊断、备份、恢复、升级和恢复 |
| [Claude 代码](docs/claude-code.md) | Claude Code的托管技能和MCP注册 |
| [Codex](docs/codex.md) | Codex的托管技能和MCP注册 |
| [架构](docs/architecture.md) | 依赖方向和守护进程所有权模型 |
| [配置](docs/configuration.md) | 平台原生位置、环境变量和安全默认值 |
| [MCP 合约 V1](docs/mcp-contract-v1.md) | 公共兼容性和响应信封规则 |
| [测试](docs/testing.md) | 标准、性能和实时验收策略 |
| [性能基准](docs/performance-baseline.md) | 10,000-note基准方法和预算 |
| [发布检查清单](docs/release-checklist-v1.md) | 当前V1验收证据和剩余发布门 |
| [实施计划](<docs/global-memory-implementation-plan(1).md>) | 原始产品需求和分阶段实施计划 |
## 项目状态
**全局代理内存** 正在进行V1开发，目前打算从源代码安装。软件包版本为`0.1.2`；MCP合约版本为`v1`。
产品名称为 **全局代理内存**。技术标识符`global-memory`、`global-memory-mcp`、`global-memoryd`、`global_memory`和`product: global-memory`对于V1兼容性保持稳定。
参见[V1发布检查清单](docs/release-checklist-v1.md)，了解已验证的场景和剩余的实时验收工作。
## 许可证
**全局代理内存** 在[pyproject.toml](pyproject.toml)中声明的MIT许可证下可用。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器