Global Agent Memory

Global Agent Memory

为 Claude Code、Codex 和其他兼容 MCP 的 Agent 提供本地优先、了解项目、持久耐用的记忆。

Global Agent Memory 让多个编码 Agent 共享一份可供审阅的记忆，而无需将知识库的控制权交给托管服务。Markdown 文件是权威数据源，混合式本地 MCP 运行时提供面向 Agent 的公开接口，仪表板则让人类能够批准、编辑、保护或删除 Agent 记住的内容。Agent 命令无需后台服务即可运行。经过身份验证的 localhost 服务会按需启动，供仪表板使用；也可以选择持续运行，以便实时监视文件并共享嵌入任务。

一个 Vault。多个 Agent。由人类掌控的记忆。

快速开始 · Obsidian Vault · 仪表板 · 工作原理 · 安全性 · MCP 契约 · 文档

为什么选择 Global Agent Memory？

编码 Agent 在会话期间很有用，但重要上下文往往会在会话之间丢失，或分散在各个客户端中。Global Agent Memory 为以下知识提供持久存储层：

• 架构决策和项目惯例；
• 经验证的工作流和运维手册；
• 反复出现的问题及其经过验证的解决方案；
• 项目偏好、实体和交接摘要；
• 为新任务或 Agent 会话提供有界上下文。

Agent 会将记忆作为候选项提交。候选项在成为持久记忆之前须由人类审阅；人类可以控制其可见性，之后也可以更新、替换、归档或彻底删除。

对比

方式	跨 Agent 共享	可供人类审阅	了解项目	访问权限由所有者控制	可移植的事实来源
CLAUDE.md / AGENTS.md	有限	✓	✓	—	✓
基础记忆 MCP	✓	不一	不一	不一	不一
托管式 Agent 记忆	✓	不一	✓	由提供方定义	—
Global Agent Memory	✓	✓	✓	✓	Markdown

将项目指令文件用于始终应包含在提示词中的精简规则。如果知识需要支持搜索、在客户端之间共享、由人工审阅、随时间更新，或通过明确权限加以保护，请使用 Global Agent Memory。

亮点

• 供多个 Agent 共享 — Claude Code、Codex 和其他 MCP 客户端使用同一个 服务和不可变的记忆 ID。
• 默认感知项目 — Git 根目录、远程仓库、别名和项目注册表 让检索范围限定在当前项目内。
• Markdown 是规范格式 — Vault 始终易于阅读、便于移植和备份， 并且可与 Obsidian 配合使用。
• 人工审核工作流 — Agent 创建候选项；所有者在仪表板中批准、编辑、拒绝或 解决冲突。
• 受保护和封存的记忆 — 敏感知识可以从常规检索中排除，并置于由所有者控制的访问权限之下。
• 本地混合搜索 — SQLite FTS5 提供关键词检索；可选的 Ollama 嵌入和 sqlite-vec 可增加语义排序。
• 适合离线使用 — 即使 Ollama 不可用，关键词搜索和生命周期操作仍可继续。
• 可重建的生成状态 — SQLite、FTS、向量、队列和缓存都可以从 Markdown 重建。
• 冻结的 MCP V1 契约 — 工具、资源、提示词、信封和兼容性规则均在仓库中进行版本管理。
• 无需运行后台服务： Claude Code、Codex 和 CLI 命令会在可选守护进程离线时，回退到进程内的同一组 MCP 应用服务。
• 本地安全边界： 启用仪表板或 HTTP MCP 时，服务会绑定到 127.0.0.1，并要求使用生成的 bearer token；该令牌存储在 Vault 之外。

专为真实项目 Vault 打造

可选择启用的性能套件会创建 10,000 条合成记忆，并运行两种运行模式共用的索引和检索流程。在记录的 macOS ARM64 基准测试中，完整重建需要 36.5 秒，热关键词搜索 P95 为 56 ms，热混合搜索 P95 为 76 ms，增量 stdio 代理开销为 1.5 ms。结果因设备而异；更改笔记、搜索和代理的预算会作为回归门槛。请参阅方法和完整基准数据。

三个界面，一个记忆系统

Global Agent Memory 不只是一个 MCP 服务。Agent、所有者和知识工作者通过三个专门打造的界面使用相同的规范记忆：

界面	面向对象	提供的功能
MCP	Claude Code、Codex 和其他 Agent	项目感知上下文、搜索、候选项创建、安全更新、生命周期操作，以及通过冻结的 V1 契约提出权限请求
Obsidian Vault	阅读、编写、链接和长期知识管理	可移植的 Markdown 和 YAML、模板、原生 Bases 视图、项目概览中心、wikilinks、反向链接、关系图导航和直接编辑同步
本地仪表板	快速审核和管理	候选项批准与编辑、冲突比较、可见性分类、受保护访问决策、搜索、项目、活动、备份和系统运行状况

Vault 是持久的事实来源。仪表板是配套的控制平面，MCP 接口则是 Agent 使用的安全自动化层。你可以使用 Obsidian、仪表板或两者兼用，无需为记忆创建单独的副本。

仪表板一览

_{使用 Atlas 项目合成数据的真实仪表板界面。未显示任何私有 Vault 内容。}

快速开始

这是为 Claude Code、Codex 和其他 MCP 客户端设置持久记忆的最短路径。引导式安装程序会一并创建本地服务、兼容 Obsidian 的 Vault、仪表板、MCP 注册信息和 Agent 技能。

要求

• macOS 或 Linux
• Python 3.12 或更高版本
• uv
• 用于托管客户端集成的 Claude Code 或 Codex
• 可选：Obsidian，用于浏览 Markdown Vault
• 可选：Ollama，用于语义检索

1. 安装

uv tool install global-memory-mcp

若要安装最新的未发布源码，请使用 uv tool install git+https://github.com/ozankasikci/global-agent-memory.git。对于 本地检出，请使用 uv tool install .。

2. 运行引导式设置

global-memory setup

设置会显示一份计划，并在进行任何更改前询问一次。它会初始化本地 Vault、创建受保护的令牌、检测 Claude Code 和 Codex、安装它们的 MCP 集成和技能、验证客户端状态正常，并打开仪表板。按需打开仪表板时，会启动经过身份验证的本地主机服务器。该命令具有 幂等性，因此再次运行时会修复或更新托管组件，而不会替换无关的客户端配置。

需要非默认设置时，可使用以下标志：

# Non-interactive installation
global-memory setup --yes

# Choose a different Vault on first setup
global-memory setup --vault "$HOME/Memory"

# Install only one client, or no client yet
global-memory setup --clients claude-code
global-memory setup --clients none

# Optional: install an always-on native service for live watching and shared indexing
global-memory setup --service

# Preview without changing files or services
global-memory setup --dry-run

3. 使用已安装的 Agent 快捷方式

设置会为每个检测到的客户端安装五个基本快捷方式：

快捷方式	用途
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. 再次打开仪表板

global-memory dashboard

你也可以向已连接的 Agent 发出请求：

打开 Global Agent Memory 仪表板。

Agent 会调用 memory_dashboard_open 并打开同一个经过身份验证的本地 仪表板。

手动安装和修复

高级设置和故障排查仍可使用各个命令：

global-memory init --vault "$HOME/Documents/Global Agent Memory"
global-memory daemon install-service --kind launchd  # use systemd on Linux
global-memory integrations install all
global-memory integrations verify all
global-memory doctor

与 Agent 搭配使用

完成集成后，通常只需描述你的意图，而不必手动运行记忆命令。

开始工作前检索上下文

开始之前，加载此项目的相关记忆，并总结其中的惯例和近期决策。

提议持久记忆

记住：生产环境的 ARM64 二进制文件必须在本地构建并上传到服务器。将其作为项目惯例添加，并以部署讨论作为依据。

Agent 会创建一个候选项。获得批准后，它才会生效。

更新现有知识

找到有关部署的记忆，并用新的健康检查命令更新它。不要创建重复项。

打开审核界面

打开记忆仪表板，以便我审核候选项。

共享集成技能会指导受支持的 Agent 何时检索、提议、更新记忆，以及如何避免重复记忆。

Obsidian 知识库

配置的 Obsidian 知识库是人类可读且持久可靠的事实来源，而不是不透明数据库的导出内容。每条受管理的记忆都是普通的 Markdown 文件，包含 YAML 属性、稳定的记忆 ID、生命周期元数据和了解项目上下文的链接。

初始化会添加 Obsidian 工作区，而不会替换现有文件：

• 包含决策、事实、解决方案、约定、偏好、实体、参考资料、会话摘要和项目概览的模板；
• 用于候选审核队列、活跃知识、近期更新、按项目查看决策、已验证解决方案和生命周期历史的原生 Bases 视图；
• 嵌入项目记忆的项目概览中心；随着笔记在候选、活跃、已拒绝、已取代或已归档文件夹之间流转，这些中心仍保持稳定；
• 用于反向链接和图谱导航的双链和双向取代链接；
• 请求时同步，因此在 Obsidian 中进行的普通内容和描述性属性编辑无需后台服务即可变为可搜索；
• 启用后台服务时，可选用监视程序同步，以便立即编入索引。

Obsidian 是可选的：使用任何文本编辑器都可以阅读和编辑相同的 Markdown。生命周期和访问策略的变更仍应通过仪表板、MCP 或 CLI 进行，以确保验证、乐观并发控制和审计记录保持完整。

仪表板

经过身份验证的仪表板是所有者控制面板，可用于：

• 项目概览和近期项目活动；
• 逐条审核和编辑候选记忆；
• 比较重复项和冲突；
• 搜索记忆并管理其生命周期；
• 设置 Standard、Protected 和 Sealed 分类；
• 审批访问请求并撤销有效授权；
• 解锁密封记忆供所有者查看，并生成审计记录；
• 切换项目、查看系统运行状况、重新编制索引和创建备份；
• 在 Obsidian 或本地文件查看器中打开规范 Markdown 文件。

_{候选审核会清晰展示证据和冲突，供所有者在批准将其作为持久记忆保存前查看。}

仪表板启动 URL 会在 60 秒后过期，只能兑换一次，并会创建本地 HttpOnly 会话。请勿分享启动 URL。

记忆可见性和访问权限

级别	Agent 的默认行为	所有者控制
Standard	纳入常规范围内的检索	按常规流程审核候选记忆和生命周期
Protected	从默认结果中排除；Agent 仅会收到中性的相关性信号	所有者选择确切的记忆、权限、时长、策略和符合条件的项目
Sealed	正文不会编入索引，也不会通过 Agent 工具返回	所有者解锁后可在仪表板中查看一次；每次访问都会记录审计信息

Protected 授权按用途、项目、Agent、权限、确切的记忆 ID 和时长限定范围。所有者可以降低请求的权限，但不能提高权限。Agent 可以请求访问并轮询请求状态，但不能批准、拒绝或撤销授权。

重要

Protected 和 Sealed 记忆不是密钥管理器。切勿在 Global Agent Memory 中存储密码、凭证、私钥、API 密钥或持有者令牌。

工作原理

flowchart LR
    A[Claude Code] -->|stdio MCP| H[Hybrid MCP runtime]
    B[Codex] -->|stdio MCP| H
    C[CLI] -->|MCP| H

    H -->|daemonless default| E[Application and domain services]
    H -.->|optional localhost daemon| D[Watcher, shared indexing, dashboard]
    D --> E
    E --> V[Markdown Vault<br/>canonical state]
    E --> I[SQLite FTS5 and sqlite-vec<br/>generated state]
    E --> O[Ollama embeddings<br/>optional]
    D --> W[Local dashboard<br/>owner control]

global-memory-mcp 桥接程序优先使用健康的共享守护进程，否则会在进程内运行相同的 MCP 服务和应用服务。两种路径都提供相同的冻结版 MCP V1 契约，并使用相同的规范 Markdown 和生成的 SQLite 状态。可选守护进程负责实时监视 Vault、在后台重试嵌入、提供 HTTP MCP 和管理仪表板会话。Agent 记忆操作不依赖守护进程是否可用。

依赖方向如下：

transport and client adapters → application services → domain

Vault、SQLite、向量、嵌入、Git、Watchdog 和客户端集成都是适配器。领域层不依赖它们。

MCP 接口

MCP 接口是唯一面向 AI 的公共 API。客户端不会直接读取 Vault、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 和生成的 contracts/mcp/v1/ 架构。

CLI 示例

CLI 使用与已连接 Agent 相同的 MCP 路径。它优先使用可选守护进程，否则通过内存传输调用冻结版 MCP 契约。它绝不会通过直接读取 Markdown 或 SQLite 绕过访问控制。

# Check health
global-memory status
global-memory doctor

# Register and detect a project
global-memory project add my-project --root "$HOME/Projects/my-project"
global-memory project detect "$HOME/Projects/my-project"

# Search and build bounded task context
global-memory search "deployment rollback" --project my-project
global-memory context "Prepare the next release" --project my-project --token-budget 3000

# Create a review candidate
global-memory remember \
  "Release rollback procedure" \
  "Use the blue-green rollback task and verify both health endpoints." \
  --type reference \
  --scope project \
  --project my-project

# Rebuild generated indexes
global-memory reindex --full

# Back up canonical Markdown
global-memory backup "$HOME/Backups/global-agent-memory.zip"

运行 global-memory --help 或 global-memory <command> --help 查看完整的命令参考。

安全模型

Global Agent Memory 旨在作为本地服务，而不是对外暴露的远程记忆 API。

• 可选的 HTTP 和仪表板服务仅限于 127.0.0.1。
• Streamable HTTP 需要生成的本地 bearer 令牌。
• 令牌、数据库、日志、锁文件和生成的状态均保存在 Vault 之外。
• 令牌文件仅对用户开放权限。
• 仪表板会话有效期短，仅限本地且设为 HttpOnly。
• 路径被限制在配置的 Vault 内，并会检查路径遍历和符号链接逃逸。
• 常规日志会对正文、提示词、嵌入、机密和授权信息进行脱敏。
• 可删除生成的状态，并从规范 Markdown 重新构建。
• 面向 Agent 的检索对受保护和封存的记忆采用默认拒绝策略。

请按照 SECURITY.md 报告安全问题。

开发

克隆仓库，然后安装 Python 和仪表板依赖：

uv sync
npm ci --prefix dashboard

运行标准质量检查：

make check

检查流程涵盖 Ruff 格式化和 lint、严格 MyPy、TypeScript 生产构建、单元／集成／契约／E2E 测试、覆盖率，以及确定性 MCP 契约再生成。

常用的专项命令：

make unit
make integration
make contract
make e2e
make dashboard-check
make performance   # opt-in 10,000-note performance suite

更改 MCP 契约时：

make contract-generate
make contract-check

欢迎贡献。请从 CONTRIBUTING.md 开始，并确保更改兼容冻结版 V1 契约，除非有意并行引入一个新的主版本契约。

社区与路线图

• 在 GitHub Discussions 中提出使用问题并分享 Agent 工作流。
• 从 good first issue 或 help wanted 列表中挑选范围明确的贡献任务。
• 在 公开路线图 中关注计划中的分发、安全和集成工作。
• 如果这个项目对你有用，为仓库加星有助于其他 Agent 工具用户发现它。

文档

指南	用途
运维	安装、守护进程管理、诊断、备份、恢复、升级和故障恢复
Claude Code	为 Claude Code 管理技能和 MCP 注册
Codex	为 Codex 管理技能和 MCP 注册
Hermes Agent	手动注册 stdio MCP 并进行已验证的检索冒烟测试
架构	依赖方向和混合运行时所有权模型
配置	平台原生位置、环境变量和安全默认值
MCP Contract V1	公共兼容性和响应封装规则
测试	标准、性能和线上验收策略
性能基线	10,000 条笔记的基准测试方法和预算
发布清单	当前 V1 验收证据和剩余发布关卡
实施计划	原始产品需求和分阶段实施计划

项目状态

Global Agent Memory 正在积极开发 V1，并通过 GitHub Releases 和 PyPI 分发。当前 GitHub 发行版和 源代码包版本为 0.1.7；MCP 合约版本为 v1。

产品名称为 Global Agent Memory。技术标识符 global-memory、 global-memory-mcp、global-memoryd、global_memory 和 product: global-memory 在 V1 中保持稳定，以确保兼容性。

请参阅 V1 发布清单，了解已验证的场景和 剩余的线上验收工作。

许可证

Global Agent Memory 采用 pyproject.toml 中声明的 MIT 许可证。