Jason 杰森的效率工坊
网站导航
← 返回资料库

Agent Memory 完整指南：用 Basic Memory 从 0 搭建长期记忆系统

什么是 Agent Memory？本教程对比 Codex、Claude Code、Hermes 的原生记忆与主流第三方方案，并演示用 Basic Memory 连接多个智能体、结合 Obsidian 搭建可检索、可维护、可共享的长期记忆系统。

发布于 下载 Markdown

Agent Memory：原生记忆和长期经验系统

Agent Memory（智能体记忆）解决的核心问题，是让智能体跨会话、跨任务甚至跨不同 Agent 保留真正有价值的信息，并在未来需要时重新找到、更新和利用这些信息。 一套完整的记忆系统通常要处理：获取信息 → 判断什么值得记 → 保存 → 检索 → 更新 → 合并 → 遗忘 → 从经历中归纳经验。

理解 Agent Memory 时最重要的一点是：记忆越多不等于 Agent 越聪明。真正影响效果的是记了什么、什么时候取回来、旧信息如何更新，以及过去经历能否改变未来行为。

Agent Memory 是什么

长期使用 Codex、Claude Code、Hermes 一类 Agent 时，至少存在三种不同的信息机制：

类型主要作用典型内容
当前上下文完成眼前任务当前对话、代码、工具结果、计划
长期指令告诉 Agent 必须怎样工作AGENTS.md、CLAUDE.md、项目规则
长期记忆保存以后可能有用的信息用户偏好、项目事实、历史决策、调试经验

Agent Memory 的意义，就是避免每次新会话都重新解释一些有长期价值的信息。

Agent 原生 Memory 机制

Agent如何开启开启后会发生什么想主动写入一条记忆用户平时要做什么
CodexDesktop：Settings → Personalization → Enable memories；或 config.toml 中设置 memories = trueCodex 会从过去的 Session 中自动提炼长期有用的信息，保存到 ~/.codex/memories/，以后需要时参考不建议直接改 Memory 文件。 普通使用不需要主动写；如果是必须长期遵守的规则，应写入 AGENTS.md主要维护 AGENTS.md。Memory 基本让 Codex 自动管理，偶尔检查即可
Claude Code默认已开启；/memory 可查看和管理，也可在设置中关闭Claude 会把构建命令、踩坑经验、用户偏好等保存到 ~/.claude/projects/<project>/memory/直接在对话里说“记住……”即可。 Claude 会自己写入 Memory；也可以直接编辑 MEMORY.md平时让 Claude 自动记，偶尔用 /memory 检查、删除错误或过期内容。必须遵守的规则写 CLAUDE.md
Hermes原生 Memory 默认可用；通过配置中的 memory.memory_enabled 控制。hermes memory setup 主要是配置第三方 Memory Provider，不是开启原生 MemoryHermes 会把少量长期信息写入 ~/.hermes/memories/MEMORY.md 和 USER.md；完整历史保存在 state.db，需要时搜索直接告诉 Hermes“记住……”即可。 它会调用 Memory Tool 写入；也可以人工编辑 MEMORY.md / USER.mdMemory 文件容量很小，只放高价值信息。建议开启写入审批，定期清理错误或过期记忆

第三方 Agent Memory

原生 Memory 的主要缺口

问题实际表现第三方 Memory 提供的能力
Agent 之间割裂Claude Code 知道，Codex 不知道共用一套 Memory
历史越来越多Markdown 或摘要无法高效覆盖大量历史全文、向量和混合检索
重复踩坑Agent 每次重新尝试已经失败过的方法保存情景/经历记忆
事实变化新旧事实同时被找回来时间、版本、冲突处理
只记不学保存了大量历史但行为没有改变反思、归纳、认知模型、Skill 演化
多设备或多人本地记忆无法自然共享云端或服务器式 Memory

主流 Agent Memory 解决方案对比

不同的产品解决不同的核心问题：

路线主要解决的问题代表工具
人类可控型人和 AI 共用、可直接编辑的长期知识Basic Memory
编码经验型保存 Coding Agent 的调试和工作经历AgentMemory、claude-mem
通用画像型用户偏好、用户事实、多应用共享上下文Mem0、Supermemory
本地综合型用较少基础设施实现高级 MemoryMnemosyne
经验成长型从经历形成认知、策略或技能Hindsight、MemOS、Letta
时间图谱型处理实体关系和不断变化的事实Graphiti / Zep

详细对比表格：

工具 / GitHub 热度分组核心定位主要记忆数据与存储检索 / 学习写入方式Codex / Claude Code / Hermes部署 / 数据位置关键判断
Basic Memory⭐ 约 3.7k人类可控Markdown 人机共享知识库事实、研究、决策、知识关系Markdown 为主，本地索引为辅关键词 + 语义检索 + WikiLink 关系用户或 Agent 主动写；插件可自动捕获Codex：MCPClaude：MCP/插件Hermes：插件本地优先；可选云端同步最适合 Obsidian、PKM 和重视数据可控性的个人用户
AgentMemory⭐ 约 27.1k编码经验多 Coding Agent 共享项目经验调试经验、失败路径、历史决策、项目上下文内置键值数据库 + 内存向量索引关键词 + 向量 + 关系图混合检索钩子（Hook）自动捕获，也可主动保存Codex / Claude / Hermes 均有插件或 MCP 集成主要本地运行很适合跨 Agent 的编码工作连续性，但应关注记忆隔离和噪声
claude-mem⭐ 约 90.9k编码经验自动保存 Coding Session 工作过程工具调用、调试、操作观察、会话摘要SQLite + 向量数据库（Chroma）全文 + 向量检索 + 分层展开Hook 自动捕获会话生命周期Claude 最成熟；Codex、Hermes 已支持本地热度很高，但与主流 Agent 原生 Memory 的重叠正在增加
Mem0⭐ 约 63.4k通用画像AI 应用的通用用户记忆层用户事实、偏好、历史事件、Agent 状态可插拔普通数据库 + 向量存储向量 + 关键词 + 实体 + 时间检索API / SDK 输入后自动提取Codex / Claude：技能或 APIHermes：官方 Provider云端或自托管生态和通用性强，更偏 AI 应用基础设施
Supermemory⭐ 约 28.9k通用画像跨 AI 工具共享用户上下文用户画像、项目上下文、历史讨论、文档知识数据库 + 向量索引知识检索 + 个性化记忆 + 事实更新自动提取，也可主动保存Claude：插件Hermes：官方 Provider Codex：MCP云端或本地适合希望把个人上下文跨多个 AI 工具共享的用户
Mnemosyne⭐ 约 2.5k本地综合单机实现较完整的高级 Memory事实、经历、重要度、有效期、时间关系单文件 SQLite + 向量/全文索引全文 + 向量 + 时间/重要度 + 时间关系MCP / 插件 / SDK；支持后台整合Codex / Claude：MCPHermes：第三方插件完全本地适合重视隐私，又希望使用数据库型高级 Memory 的个人用户
Hindsight⭐ 约 20.0k经验成长从经历形成更高层认知事实、经历、实体关系、认知模型PostgreSQL / 内嵌 PG + 向量/图索引语义 + 关键词 + 图关系 + 时间 + 反思Retain 自动抽取；支持后台整合和 ReflectCodex / Claude：官方 Coding Agents 集成Hermes：官方 Provider本地、Docker、自托管或云端最典型的“经历 → 反思 → 认知”成长型方案
MemOS⭐ 约 10.7k经验成长管理多类 Memory 并演化策略与 Skill事实、工具轨迹、策略、世界模型、技能完整版：图数据库 + 向量数据库本地插件：SQLite + Skill 文件混合检索 + 调度 + 反馈纠正 + 技能演化自动处理；可根据反馈持续学习Hermes 集成最深；Codex / Claude 可经 API/MCP 接入云端、自托管或本地插件成长理念很强，但完整版与本地插件必须分开理解
Letta（原 MemGPT）⭐ 约 24.3k经验成长把 Memory 作为有状态 Agent 自身机制长期状态、历史消息、外部资料、自维护上下文Letta Server 统一管理状态与 MemoryAgent 主动读写、重组长期状态Agent 运行过程中主动维护不是 Codex / Claude / Hermes 的主流外挂路线云端或自托管研究价值高，更适合直接构建 Letta Agent
Graphiti / Zep⭐ Graphiti 约 30.0k时间图谱处理实体关系和不断变化的事实实体、事件、关系、来源、有效时间图数据库 + 向量/全文索引图关系 + 向量 + 关键词 + 时间检索写入事件后自动抽取实体和关系主要通过 MCP 等通用方式接入Graphiti 可自托管；Zep 有云端服务复杂关系和时间变化场景很强，普通个人用户通常偏重

总体架构：

%%{init: {"flowchart": {"useMaxWidth": true, "htmlLabels": true, "nodeSpacing": 24, "rankSpacing": 36, "padding": 10}}}%%
flowchart LR
    subgraph agent_side["智能体这一侧"]
        direction TB
        agent["Agent<br/>Claude Code / Codex / Hermes 等等"]
        tools["工具<br/>Hook · 插件 · Skill · MCP"]
        agent --- tools
    end

    subgraph memory_tool["Agent Memory 工具"]
        direction TB
        products["具体工具<br/>Basic Memory · Hindsight · Mem0 · 其他"]
        mechanism["核心机制<br/>1.记忆模型<br/>2.采集、演化、检索<br/>3.关系、时间、事实"]
        storage["真正存东西的地方<br/>Markdown · 向量库 · SQL · 图数据库 · 索引"]

        products --- mechanism
        mechanism --- storage
    end

    tools <--> products

    style agent_side fill:#f3d9fa,stroke:#862e9c,stroke-width:2px
    style agent fill:#e5dbff,stroke:#5f3dc4,stroke-width:2px
    style tools fill:#e5dbff,stroke:#5f3dc4,stroke-width:2px

    style memory_tool fill:#e7f5ff,stroke:#1971c2,stroke-width:2px
    style products fill:#c5f6fa,stroke:#0c8599,stroke-width:2px
    style mechanism fill:#c5f6fa,stroke:#0c8599,stroke-width:2px
    style storage fill:#d3f9d8,stroke:#2f9e44,stroke-width:2px

Agent Memory 排行榜应该怎么看

目前常见的 Memory Benchmark（记忆评测）包括 LoCoMo、LongMemEval、BEAM 等。

这些评测不能直接把不同项目官网公布的分数拿来排大小，因为它们可能使用：不同数据集 → 不同大模型 → 不同检索数量 → 不同提示词 → 不同评分模型 → 不同云端/开源版本。 因此：Hindsight 的某个 90 分，不等于一定比 Mem0 的某个 88 分强。分数只有在相同测试协议下才具有直接横向比较价值。

Agent Memory Leaderboard（AML）的价值就在这里：它尝试把参赛 Memory 系统主要限制在“写入”和“检索”能力上，再统一后续回答模型与评分模型，从而减少“产品用了更强大模型所以分更高”的污染。

AML 还把 Memory 拆成多个能力维度，并单独关注 Coding Agent 的：

  • 调试记忆：过去的错误、修复和失败经验能不能复用；
  • 开发记忆：过去的架构决定和工程知识能不能重新利用。

这比单纯测试“AI 是否记得用户喜欢什么”更接近 Coding Agent 的真实工作。

第三方 Memory 应该怎样选

选择顺序应该从问题出发：

原生 Memory 已经够用 → 不安装第三方。 需要 Obsidian、人类可读、不同 Agent 共享知识 → Basic Memory。 需要 Coding Agent 自动保存失败路径和历史工作经验 → AgentMemory 一类工具。 需要为 AI 应用维护用户画像和长期事实 → Mem0 / Supermemory。 希望 Agent 从经历中反思并形成认知 → Hindsight。 希望进一步管理记忆生命周期，并把高价值经验演化成 Skill → MemOS。 需要处理复杂实体关系和事实随时间变化 → Graphiti / Zep。

不要反过来因为某个项目 GitHub Star 很高，就先装上再找用途。

Basic Memory：轻量、人类可控的长期知识层

Basic Memory 代表了一条非常明确的路线：Markdown 才是用户真正拥有的数据，数据库和搜索系统只是辅助层。 它让人和多个 Agent 直接读写同一批 Markdown。

Basic Memory 的结构

flowchart LR
    C[Codex] --> M[MCP]
    A[Claude Code] --> M
    H[Hermes] --> M
    M <--> B[Basic Memory]

    B <--> F[Markdown 文件]
    F <--> O[Obsidian<br/>人类可读 / 可编辑]

    F --> P[解析 Markdown]
    P --> I[SQLite<br/>全文 · 向量 · 知识图谱]
    I --> B

Markdown 是真正的长期知识资产。所以即使未来 Basic Memory 停止维护，你的核心数据仍然只是普通 Markdown。

本地安装

Basic Memory 当前要求 Python 3.12+。 使用 uv命令在本地安装basic-memory：

# 安装 Basic Memory CLI。
uv tool install basic-memory

# 确认安装成功。
basic-memory --version

默认知识目录通常位于：~/basic-memory/。 可以运行：

basic-memory status
basic-memory project list

检查当前状态和项目。

创建 Basic Memory Project

比如你想要在这个本地文件夹内保存你的智能体长期记忆：~/jason-memory/。（注意，也可以指定你的Obsidian Vault中的特定文件夹，这样一来就可以把它作为你的长期知识资产了。） 先创建并设为默认 Project：

bm project add "jason-memory" '/Users/jason/Obsidian/my-ob-vault/90 - System/Memory'
bm project default "jason-memory"

一个 Project 本质就是一个独立知识库；需要互相搜索、建立 Wiki Link 和关系的内容，应该放在同一个 Project。

连接 Codex、Claude Code 和 Hermes 并进行初始化

来到智能体中，安装插件，并运行初始化命令，分别为不同的 Agent 绑定这个project：

Codex

Codex版本的Plugin 自带 MCP、Skills 和 Hooks。

# 注册 Basic Memory Plugin marketplace
codex plugin marketplace add basicmachines-co/basic-memory
# 安装 Plugin
codex plugin add codex@basic-memory

然后$bm-setup 然后选择primaryProject = jason-memory，它会写入 ~/.codex/basic-memory.json 或当前项目的 .codex/basic-memory.json。

Claude Code

目前Claude Code的plugin不带MCP，这个要注意。所以完整安装命令是：

# 1. 连接 Basic Memory MCP
claude mcp add basic-memory -- uvx basic-memory mcp

# 2. 注册 Basic Memory Plugin marketplace
claude plugin marketplace add basicmachines-co/basic-memory \
  --sparse .claude-plugin plugins/claude-code

# 3. 安装 Plugin
claude plugin install basic-memory@basicmachines-co

然后/basic-memory:bm-setup 然后选择jason-memory作为primaryProject。这个命令会完成 Project 映射、Schema 初始化等配置。

Hermes Agent

Hermes特有的插件安装机制，可以直接安装Plugins：

# 1. 安装 Basic Memory Plugin
hermes plugins install basicmachines-co/basic-memory/integrations/hermes

# 2. 初始化并选择 Basic Memory 作为记忆系统，然后设置`project = jason-memory`
hermes memory setup basic-memory

# 3. 检查状态
hermes memory status

最终效果：三个智能体统一使用同一个记忆库。

		~/jason-memory/
			  │
		Basic Memory
			  │
  ┌───────────┼───────────┐
  ↓           ↓           ↓
Codex      Claude Code   Hermes

安装官方通用skills plugin add命令只会安装bm skill。

basic-memory/
├── plugins/
│   ├── codex/skills/          ← Codex Plugin 专用 bm-* Skills
│   └── claude-code/skills/    ← Claude Plugin 专用 bm-* Skills
│
└── skills/                    ← 跨 Agent 通用 memory-* Skills

而官方还提供了一套通用skills：

npx skills add basicmachines-co/basic-memory/skills

plugin自带的skills以及官方额外提供的skills

Skill来源核心功能平时怎么用更合适日常重要性
bm-setup🔵 Plugin 自带：Codex / Claude Code**第一次配置 Basic Memory。**选择使用哪个 Memory Project、记忆保存到哪里、是否开启自动记录等**首次安装后手动运行一次。**以后一般不用管⭐⭐⭐⭐⭐
bm-orient🔵 Plugin 自带：Codex / Claude Code**“看看我们之前做到哪了”。**读取最近任务、决定和工作记录，恢复上下文主要让 Agent 在继续旧任务时自己用；你也可以主动说“恢复之前的工作”⭐⭐⭐⭐⭐
bm-checkpoint🔵 Plugin 自带：Codex / Claude Code**保存当前工作进度快照。**记录目标、已经做了什么、未解决问题和下一步插件在上下文压缩时会配合自动使用；你结束重要工作前也可以主动调用⭐⭐⭐⭐⭐
bm-decide🔵 Plugin 自带：Codex / Claude Code**专门保存重要决定。**不仅记“选了什么”，还记为什么这么选、放弃了什么方案重要决定最好让 Agent 主动识别；特别重要时你也可以明确说“记录这个决定”⭐⭐⭐⭐⭐
bm-remember🔵 Plugin 自带：Codex / Claude Code；Hermes 有 /bm-remember**快速记住一件事。**适合你明确说“记住这个”**主要给用户主动触发。**例如“记住以后技术调查优先官方资料”⭐⭐⭐⭐⭐
bm-share🔵 Plugin 自带：Codex / Claude Code把个人 Basic Memory 中的一篇记忆复制到团队共享 Project只有使用 Basic Memory Cloud 团队空间时才手动用⭐
bm-status🔵 Plugin 自带：Codex / Claude Code；Hermes 有对应状态命令查看 Basic Memory 是否正常、当前使用哪个 Project、最近有没有成功保存出现问题或刚配置完成时手动检查⭐⭐⭐
bm-writing🔵 Plugin 自带：Codex / Claude Code**规定 Agent 写记忆时应该怎么写。**包括结构、表达方式、关系链接等主要交给 Agent 自动使用。用户一般不主动调用；想改变记忆写法时才修改它⭐⭐⭐⭐
basic-memory🔵 Hermes Plugin 自带Hermes 的“Basic Memory 使用说明”。告诉它什么时候搜索记忆、什么时候写记忆，以及怎样使用 bm_* 工具交给 Hermes 自动使用即可，通常不需要用户主动调用⭐⭐⭐⭐⭐
memory-notes🟢 官方通用 Skill，需通过 npx skills add 安装**教 Agent 怎样写一篇规范的 Basic Memory 笔记。**怎么写标题、事实、关系、Wiki Link，并强调写之前先搜索旧记忆主要让 Agent 自动参考，不需要你频繁手动调用⭐⭐⭐⭐⭐
memory-reflect🟢 官方通用 Skill**回顾最近的聊天和 Session，把真正值得长期留下的信息挑出来。**例如重要决定、经验、长期偏好**适合主动或定期执行。**例如每天一次；以后我们最好改成符合自己 core/、projects/ 等结构的版本⭐⭐⭐⭐⭐
memory-capture🟢 官方通用 Skill**把当前这场讨论整理成一篇干净的总结。**不是聊天流水账，而是记录最终结论一场重要研究、规划或讨论结束时可以手动调用；Codex/Claude 已有 checkpoint，所以不用每次都用⭐⭐⭐
memory-continue🟢 官方通用 Skill**恢复以前做过的事情。**搜索相关 Memory，然后把必要背景重新读出来用户说“继续上次那个项目”时让 Agent 自动用；Codex/Claude 已有 bm-orient，所以有一定重复⭐⭐⭐
memory-reflect🟢 官方通用 Skill从最近多次工作记录中提炼真正的长期记忆，而不是简单保存 Session这是最适合定期主动运行的 Skill 之一⭐⭐⭐⭐⭐
memory-ingest🟢 官方通用 Skill**把旧资料导入 Basic Memory。**例如旧 Codex Memory、Claude Memory、聊天记录、会议记录等，整理成结构化记忆**主要由用户主动使用。**尤其适合你第一次迁移旧长期记忆时⭐⭐⭐⭐
memory-lifecycle🟢 官方通用 Skill**管理记忆的“生命周期”。**例如项目结束后不要删除，而是移动到归档；旧状态被新状态替代日常可以交给 Agent判断；大规模整理时可以主动调用⭐⭐⭐⭐
memory-defrag🟢 官方通用 Skill**给记忆库“大扫除”。**找重复内容、过时信息、越来越臃肿的文件，然后合并或拆分建议隔一段时间主动执行，例如几周一次，而不是每天用⭐⭐⭐⭐
memory-curate🟢 官方通用 Skill**整理记忆之间的关系。**找孤立笔记、重复主题、缺失链接，把整个知识图谱整理得更好Memory 积累比较多以后偶尔主动运行⭐⭐⭐
memory-tasks🟢 官方通用 Skill**把 Basic Memory 当任务管理器。**保存多步骤任务、进度、当前状态，跨 Session 继续只有你确实希望 Basic Memory 同时管理任务时使用；否则不必主动用⭐⭐
memory-schema🟢 官方通用 Skill**规定同一类记忆应该有哪些固定字段。**例如“项目”“决定”“会议”都使用统一结构初期基本不用管；Memory 规模很大、结构开始混乱后再使用⭐⭐
memory-metadata-search🟢 官方通用 Skill按固定字段精确找记忆。例如“找所有还没完成的项目”“找优先级高的任务”大多数时候让 Agent 自动使用；只有做复杂筛选时才明显有价值⭐⭐
memory-research🟢 官方通用 Skill**做网络调查后，把研究结果直接整理进 Basic Memory。**还会先看看已有记忆，避免重复研究适合明确说“调查这个主题并保存进 Basic Memory”时使用；不是每次搜索都需要⭐⭐⭐
memory-onboarding🟢 官方通用 Skill**帮新用户从零设计一套 Basic Memory。**会询问需求，然后创建结构、规则、入口文件等基本是一次性主动运行；而我们已经自己设计 START.md 和 MEMORY_POLICY.md，价值反而降低⭐⭐
memory-literary-analysis🟢 官方通用 Skill专门把一本书拆成角色、主题、章节、地点等结构化记忆只有分析小说、书籍时才主动用，对日常 Agent Memory 几乎没用⭐

Agent 的原生 Memory 文件是否会与 Basic Memory 冲突？

Basic Memory 官方不主张把 Agent 原生 Memory 全部删除。 官方文档有一篇：Using Basic Memory with Built-in AI Memory

Built-in memory = short-term cache (Agent 原生 Memory → 小型、工具专属、快速加载) Basic Memory = long-term store (Basic Memory → 大型、结构化、跨 Agent 的长期知识)

初始化，以及Basic Memory的文件结构设计

方式一：memory-onboarding skill

memory-onboarding skill 会执行以下流程：调查需求 → 提出目录结构 → 让用户批准 → 创建规则、结构、Note → 创建真实示例 → 配置 Agent 启动时如何读取。

文件夹示例：

basic-memory-project/
├── instructions/                              ← 系统入口和各类长期操作规则
│   ├── 启动路由.md                             ← AI 使用知识库前首先读取的场景路由
│   ├── Basic Memory 使用速查.md                ← 面向用户的常用指令、Skill 和维护入口
│   ├── 个人上下文规则.md                        ← 个人背景与当前方向的读取、更新边界
│   ├── AI 协作规则.md                          ← 根据任务场景加载对应输出偏好
│   ├── 项目知识规则.md                          ← 项目摘要、状态和关键决策的维护规则
│   └── 记忆迁移规则.md                          ← 从对话、笔记和项目仓库提炼长期记忆
│
├── profile/                                   ← 相对稳定的个人背景与阶段性方向
│   ├── Jason 的个人背景.md                     ← Jason 的稳定背景、能力范围和常用环境
│   └── Jason 的当前工作方向.md                 ← 当前 Jason 的主要工作方向
│
├── preferences/                               ← AI 在不同任务场景下需要遵守的偏好
│   ├── 通用协作偏好.md                          ← 默认加载的沟通方式和协作边界
│   ├── 写作与输出规范.md                        ← 普通写作、技术解释和真实性要求
│   ├── Markdown 知识笔记规范.md                ← 输出完整 Markdown 知识笔记时的格式
│   ├── 目录与架构展示规范.md                    ← 文件夹和项目架构的树形展示格式
│   └── 技术结构与 Mermaid 规范.md              ← 流程、依赖和 Mermaid 图表的使用规则
│
├── projects/                                  ← 项目级长期摘要和统一入口
│   ├── 项目索引.md                              ← 所有长期项目的状态、阶段和入口
│   └── {repository-slug}/                     ← 使用稳定仓库标识区分不同项目
│       └── {项目中文名称}.md                    ← 项目目标、阶段、关键下一步和来源入口
│
├── codex/                                     ← Codex 插件管理的工作记忆
│   ├── decisions/                             ← 需要跨会话保留的正式决策
│   │   └── {项目名称：决策主题}.md              ← 决策内容、理由、替代方案和长期影响
│   │
│   └── {workspace-name}/                      ← 按工作区保存 Codex 恢复记录
│       └── Codex checkpoint - {时间} - {主题}.md
│                                               ← compact 后生成的不可变工作交接快照
│
├── templates/                                 ← 创建结构化记忆笔记时使用的中文模板
│   ├── 个人上下文模板.md                        ← 个人背景和当前方向模板
│   ├── 偏好规范模板.md                          ← 场景化偏好模板
│   ├── 项目摘要模板.md                          ← 项目目标、状态和下一步模板
│   ├── 决策模板.md                              ← 决策、理由、替代方案和影响模板
│   ├── 指令笔记模板.md                          ← 路由和领域规则模板
│   ├── Codex 会话模板.md                       ← Codex 会话与恢复记录模板
│   └── Codex 任务模板.md                       ← 需要跨会话追踪的任务模板
│
└── schemas/                                   ← 定义各类笔记必须遵守的数据结构
    ├── 个人上下文.md                            ← 个人背景类笔记的字段和状态规范
    ├── 偏好规范.md                              ← 场景化偏好笔记的字段规范
    ├── 项目.md                                  ← 项目摘要的目标、状态和下一步规范
    ├── 决策.md                                  ← 长期决策的理由、影响和关系规范
    ├── 指令.md                                  ← 启动路由和领域规则的结构规范
    ├── Codex 会话.md                           ← checkpoint 与会话记录规范
    └── Codex 任务.md                           ← 跨会话任务的状态和字段规范

方式二：用户主导

自己来设计文件夹结构。思考：对你来说，哪些类别的记忆应该保存：

类型目录本质主要写入方式
核心记忆core/“用户是谁”Reflection 为主；极明确事实可即时更新
当前上下文context/“现在最关心什么”Agent + Reflection 持续更新
程序记忆procedures/“以后应该怎么做”Reflection 提炼经验后更新
项目记忆projects/“这个长期项目现在是什么状态”Agent 工作时更新 + Reflection 校正
决策记忆decisions/“为什么做出这个重要选择”即时捕获为主
情景记忆sessions/“某次工作具体发生过什么”Plugin / Hook 自动生成
历史记忆archive/“以前有效、现在已失效的内容”Reflection / Lifecycle 移入

然后让智能体为你构建。

现有 Agent 项目如何提炼memory

  1. 有旧聊天文本（比如GPT聊天记录）、旧 Memory 文件、文档：memory-ingest skill
  2. 某个特别重要的长对话：memory-capture skill
  3. 完整的、已完成的项目：
只读审计当前项目，并为 jason-memory 提炼长期项目记忆。

先读取 Basic Memory 的“启动路由”和现有项目笔记，再检查仓库中的 AGENTS.md、README.md等重要文档以及关键配置和必要代码。

只保留具有长期价值的项目目标、当前阶段、关键下一步、关键决策和设计理念。不要把临时任务、完整代码细节、日志或普通开发过程写入长期记忆。

先与现有记忆去重，向我提供：
1. 建议新增或更新的内容；
2. 对应的目标笔记；
3. 信息依据；
4. 不建议保存的内容及原因。

暂时不要写入 Basic Memory，等我确认。
  1. 然后就可以正常使用了：
新工作
→ Plugin 自动产生 Session / Checkpoint
→ bm-decide 保存关键决定
→ bm-remember 保存明确事实
→ memory-ingest 导入 ChatGPT 对话、Obsidian 笔记或外部文档时
→ memory-capture 一段重要长对话结束，需要提炼当前结论时。
→ projects/*.md 持续更新

Basic Memory 官方文档明确写：

Because Basic Memory uses standard markdown with wiki links, Obsidian understands your knowledge base natively.

所以Basic Memory 自己会解析双链语法。 Basic Memory 官方甚至专门建议把它的目录直接作为 Obsidian Vault，并使用 Graph View、Backlinks、Tags。

			 同一套 Markdown
				  │
	  ┌───────────┴───────────┐
	  ↓                       ↓
   Human                     AI
	  ↓                       ↓
  Obsidian                  MCP
  VS Code                  Codex
  Git                      Claude

如何保证Agent 每次都读取长期记忆？

官方明确说：

Connecting Basic Memory over MCP gives your assistant the tools. It doesn’t teach it when to reach for them. 所以：有 MCP ≠ Agent 一定会调用 MCP。

Basic Memory给出三种方案：

方案一：编写AGENTS.md和CLAUDE.md

## Basic Memory

在回答有关过往工作、决策、偏好或项目历史的问题之前，优先检索基础记忆库。 
使用「my‑memory」项目。 
开启新会话时，在开展实质性工作前，加载启动路由以及相关的有效上下文。

方案二：Skills

npx skills add basicmachines-co/basic-memory/skills

里面有 memory-notes、memory-onboarding、memory-ingest、memory-continue、memory-curate、memory-defrag 等。 Skills 会告诉 Agent：什么情况下搜索、怎么写 Note、怎么恢复上下文、怎么维护 Graph。但是 Skill 依然属于 Agent 行为层，而不是强制生命周期事件。

方案三：Plugin + Hooks Plugin + Hooks 可以让“每次 session 尝试恢复记忆”成为默认生命周期行为，但 Basic Memory 有意没有设计成记忆失败就禁止 Agent 工作。

内容作用
.mcp.json自动配置 Basic Memory MCP
hooks/hooks.json注册生命周期 Hooks
hooks/session_start.pySession 启动
hooks/pre_compact.pyContext 压缩前
skills/Codex 专用工作流
schemas/Codex Session / Decision / Task schema

智能体如何保存和更新长期记忆？

机制本质解决的问题不负责什么
MCP工具接口“怎么写”不决定什么时候写
AGENTS.md常驻规则“什么值得写”不保证某个时刻一定执行
Skill工作流程“发现候选记忆后，具体怎么判断、分类、去重、写入”不负责触发时机
Hook生命周期触发器“什么时候执行某件事”自己不会判断信息有没有长期价值
定时任务周期触发器“每天/每隔多久整理一次”不定义整理规则

AGENTS.md 样例：

## Long-term Memory

Basic Memory 是跨 Agent 的长期记忆真源。

主动保存真正具有长期价值的信息，而不是等待用户明确说“记住”：

- 稳定的用户事实、偏好和长期约束；
- 用户做出的明确且会影响未来工作的决定；
- 长期有效的工作方法、经验和教训；
- 项目的重要状态变化、目标和未解决问题。

不要把普通聊天、临时状态、未经确认的猜测直接写入长期记忆。

不确定长期价值的信息先保留在 session/checkpoint。

写长期记忆前先搜索已有 Note：
- 已存在 → 更新；
- 已过期 → 替换或标记 superseded；
- 不存在 → 创建。

Basic Memory 是长期事实源，不要同时维护另一套重复长期记忆。

不同智能体的记忆写入能力：

自动写长期记忆的能力CodexClaude CodeHermes
用户明确说“记住这个”✅ 自带 bm-remember Skill，可以直接写入 Basic Memory✅ 自带 bm-remember 等 Skill✅ 自带 /bm-remember 和写入工具
用户明确做出一个重要决定时，保存这个决定✅ 自带 bm-decide Skill；Agent 可以调用它保存“决定 + 原因 + 影响”✅ 自带决定记录能力，而且官方插件还能要求 Claude 主动识别重要决定并保存⚠️ 有 Basic Memory 写入工具，但没有 Claude 那么完整的“自动识别重要决定”规则；建议额外配置记忆写入规则
对话太长、上下文即将压缩时，自动保存当前工作进度✅ 自带 Hook，会保存 checkpoint（工作进度快照）✅ 自带 Hook，会在压缩前保存当前工作❌ 不采用这种机制；Hermes 走的是“每轮自动记录”路线，不需要另外补这个 Hook
自动记录每一轮聊天内容❌ 默认不记录每一轮；也不建议额外开启，否则记忆量会非常大❌ 默认不记录每一轮；也不建议额外开启✅ 自带，每轮用户和 Agent 的对话都会写入 Session 记录
一次会话结束后，自动生成会话总结⚠️ 有 checkpoint，但不是“每次聊天结束自动总结”；如确实需要，可额外安装官方 memory-capture Skill⚠️ 有 checkpoint；需要更完整的会话总结时，可额外安装官方 memory-capture Skill✅ 自带，Session 结束时自动生成 Summary（会话总结）
从最近多个会话里，自动找出“哪些内容值得成为真正长期记忆”⚠️ 需要额外安装 Basic Memory 官方 memory-reflect Skill⚠️ 需要额外安装/启用官方 memory-reflect Skill⚠️ 需要额外安装官方 memory-reflect Skill
自动发现“用户形成了一个新的长期偏好”，并更新 core/preferences.md❌ 官方 memory-reflect 默认不知道我们自己的 core/preferences.md 结构；需要修改或创建自己的长期记忆整理 Skill❌ 同左，需要自定义长期记忆整理 Skill❌ 同左，需要自定义长期记忆整理 Skill
自动把记忆正确分类到 core/、context/、procedures/、projects/、decisions/❌ 需要我们自己定义 MEMORY_POLICY.md，并让自定义 Skill 按这个规则写❌ 同左❌ 同左
写新记忆前先搜索旧记忆，避免重复⚠️ Basic Memory 官方 Skill 已经有“先搜索再创建”的原则，但我们的长期记忆整理 Skill仍应明确写入这条规则✅ Claude Basic Memory 插件对此支持比较完整，会主动搜索已有记忆⚠️ 有搜索工具，但长期记忆整理时仍需在 Skill 中明确要求“先搜再写”
新信息和旧记忆冲突时，自动更新旧内容，而不是同时保留两个矛盾版本❌ 需要我们自己的长期记忆整理 Skill 定义“更新、替代、保留历史”的规则❌ 同左❌ 同左
自动把已经过期的当前状态移入 archive/⚠️ Basic Memory 官方有 memory-lifecycle Skill，可以额外安装，用来移动、归档过期内容⚠️ 可额外安装官方 memory-lifecycle Skill⚠️ 可额外安装官方 memory-lifecycle Skill
定期整理整个长期记忆库，例如每天检查一次最近 Session❌ Agent 插件本身不会每天自动执行；需要定时任务调用 memory-reflect 或我们的自定义 Skill❌ 同左❌ 同左；Hermes 虽然记录得最勤，但也不会自动完成这种长期整理

平时应该怎么使用 Basic Memory

Basic Memory 更适合有意识地保存高价值知识，而不是把每一句对话都自动塞进去。

需求示例提示
保存项目决定“把我们为什么放弃方案 A、最终选择方案 B 的原因保存到 Basic Memory。”
保存研究结论“把今天关于 Hindsight 的核心结论整理进长期知识，并保留来源。”
查找过去知识“搜索 Basic Memory，看看以前有没有研究过类似的 Agent Memory 方案。”
继续旧项目“读取这个项目过去的决策、当前状态和未完成事项，然后继续工作。”
修正旧知识“找到之前关于这个工具安装方式的笔记，按照最新版本更新，不要新建重复笔记。”

真正好的使用方式不是：保存今天全部聊天记录。而是：把真正值得以后重新使用的结论、理由和经验整理成长期知识。

多智能体协同中的作用

Basic Memory 为多个 Agent 提供共享的长期知识与交接层，用于保存项目目标、关键决策、协作约束、验证结果和任务 checkpoint。它能减少重复调查与认知分叉，让不同 Agent 在跨任务、跨对话和上下文压缩后，仍能基于一致信息继续工作。

它不负责实时调度、消息传递或文件冲突处理，也不能替代代码、数据库和项目文档这些事实来源。

场景举例：跨对话记忆

当我和 Codex 聊了几十轮对话，然后开启了一个新对话，新对话中如何记住之前聊过的信息？

第一种：是重要信息直接保存： 当你明确在对话中要求保存重要信息和决策的时候，bm-decide和bm-remember会记录进 Basic Memory 长期记忆，后续即使这个 Codex 对话彻底删除，Markdown 文件还在。

第二种：跨长会话最关键的bm-checkpoint。 当前 Basic Memory Codex Plugin 注册了两个 Hook：SessionStart & PreCompact。 其中：PreCompact就是当 Codex 对话太长、上下文即将压缩时触发。之后 Codex 完成上下文压缩重新进入 Session 时，Basic Memory 会要求它执行 bm-checkpoint，把压缩后的工作状态写成一个持久化 checkpoint（工作交接快照）。 如果没有触发 Hooks，可以在旧对话中手动调用$bm-checkpoint，或者发送指令：“把当前工作保存为 Basic Memory checkpoint。”

版本升级

Basic Memory当前比较活跃，版本更新后，如何更新本地安装的组件： 检查核心版本：

basic-memory update --check
basic-memory --version

升级本地安装的核心组件：

uv tool upgrade basic-memory
basic-memory --version
basic-memory doctor

升级 Codex 插件（也可以发送自然语言指令，让codex自己去更新）：

codex plugin marketplace upgrade basic-memory
codex plugin list --marketplace basic-memory --json

升级所有全局 skills：

npx skills update -g