1. 项目概述：为AI编程助手构建持久化记忆系统

如果你和我一样，日常开发中重度依赖Claude Code、Cursor这类AI编程助手，那你一定遇到过这个痛点：每次开启一个新的对话会话，AI助手就像得了“健忘症”，完全不记得你之前是谁、在做什么项目、有什么特殊偏好。你不得不一遍又一遍地重复介绍自己：“我是后端工程师”、“我们项目用的是TypeScript”、“部署窗口是每周三下午”。这种重复劳动不仅低效，更关键的是，它阻碍了AI助手真正成为你的“长期搭档”——一个能记住你工作习惯、项目上下文和个人偏好的智能伙伴。

agent-memory 这个开源项目，就是为了解决这个核心痛点而生的。它是一个轻量级、本地优先的持久化记忆系统，专门为AI编程助手设计。简单来说，它在你本地电脑上运行一个SQLite数据库，让所有你使用的AI助手（无论是Claude Code、Cursor、Aider还是Gemini CLI）都能共享同一个“记忆库”。你告诉一个助手的信息，其他助手在下一次会话中也能“回忆”起来。它的工作原理是通过一个“钩子”（hook）脚本，在每次你向AI发送消息前，自动查询这个记忆数据库，并将相关的上下文信息（比如你的职业、项目关键决策、今天的日志）作为前缀注入到对话中，AI助手在回复时就能看到这些背景信息。

这个项目的核心价值在于“一次录入，处处可用”。想象一下这样的场景：周一你用Claude Code讨论了一个新的微服务架构决策，并让它记住“API网关的认证层决定采用JWT”。周二你切换到Cursor继续开发，在讨论相关代码时，Cursor会自动看到这条决策记录，避免提出与既定方案冲突的建议。这不仅仅是省去了重复输入的时间，更是让AI助手的工作流具备了连续性和一致性。

2. 核心架构与设计思路拆解

2.1 为什么选择SQLite作为存储后端？

agent-memory 的核心存储是一个SQLite数据库（ ~/.agent-memory/memory.db ）。这个选择看似简单，实则经过了深思熟虑，完美契合了项目的目标和场景。

首要考量是零依赖与极致轻量。 AI助手本身已经是资源消耗大户，为其增加的记忆系统绝不能成为新的负担。SQLite作为一个进程内数据库，无需安装和运行独立的数据库服务（如PostgreSQL或MySQL），它只是一个 .db 文件。Python 3.9+和大多数Linux/macOS系统都内置了SQLite支持，这意味着 agent-memory 在绝大多数开发者的机器上可以做到真正的“开箱即用”，没有任何额外的环境配置负担。这对于一个旨在提升体验的工具来说至关重要，安装复杂度每增加一分，用户流失率就可能呈指数上升。

其次是读写性能与并发安全。 AI助手的交互是高频、低延迟的。每次用户提问前，钩子脚本都需要查询数据库并生成上下文。SQLite在应对这种轻量级、高并发的读操作（每个会话可能触发多次查询）时表现优异。虽然它不适合高并发的写操作，但在 agent-memory 的场景下，“写”操作（保存新记忆）的频率远低于“读”操作，且通常由AI助手在后台异步执行，不会阻塞用户交互。SQLite的ACID事务特性也保证了即使在多个AI助手进程同时尝试写入时（虽然不常见），数据的一致性和完整性也不会被破坏。

最后是灵活性与可控性。 使用SQLite意味着所有数据都存储在你本地的一个文件里。这带来了几个关键优势：第一是 隐私安全 ，你的所有记忆（工作内容、个人偏好）都不会离开你的电脑，这对于处理公司代码和敏感信息的开发者来说是底线要求。第二是 可移植性和备份 ，你可以轻松地复制、备份这个 .db 文件，甚至通过 mem export/dump 命令导出为JSON，在不同机器间迁移你的“AI记忆”。第三是 可扩展性 ，项目暴露了 mem query 命令，允许执行原始SQL，为高级用户提供了无限的自定义查询和分析可能。

2.2 三层架构：钩子、CLI与数据库的协同

agent-memory 采用了清晰的三层架构，每一层职责分明，共同构成了一个既自动化又支持手动干预的系统。

第一层：钩子与上下文注入（自动化层）。 这是实现“无感记忆”的关键。以Claude Code为例，安装后会在其配置目录（ ~/.claude/settings.json ）的 hooks 部分注册一个 UserPromptSubmit 钩子，指向 mem-context-hook 脚本。这个脚本的工作流程是：

1. 触发 ：每次你在Claude Code界面按下回车发送消息时，Claude Code的运行时都会自动执行这个钩子脚本。
2. 查询 ：脚本调用 mem 库函数，连接本地的 memory.db ，执行预定义的查询。它会获取所有 facts （事实）、 soul （偏好）以及当天 daily_logs （日志）的记录。
3. 格式化与注入 ：脚本将这些查询结果格式化为一个结构清晰的Markdown块，例如：

   === MEMORY CONTEXT [Tue 18 Mar 2026, 09:15] ===
   FACTS:
   work / employer: Acme Corp
   work / role: backend engineer
   decisions / deploy-freeze: starts March 20
   SOUL:
   tone: prefers direct answers without preamble
   TODAY‘S LOG:
   - 09:00: Started debugging authentication middleware.
   === END MEMORY CONTEXT ===
   

4. 注入 ：脚本将这个文本块输出到标准输出。Claude Code的钩子系统会捕获这个输出，并将其 自动拼接 在你实际输入的用户消息之前。因此，AI模型看到的完整提示是“记忆上下文 + 你的问题”。这个过程对用户完全透明，你无需任何额外操作。

注意 ：不同AI助手对钩子的支持程度不同。Claude Code和Gemini CLI原生支持最好，可以做到全自动。对于Cline、Cursor等，可能需要通过自定义规则文件或包装脚本来模拟这一过程，这也是项目文档中为不同助手提供不同配置指南的原因。

第二层：统一CLI工具（交互层）。 mem 命令行工具是用户和AI助手与记忆系统交互的主要桥梁。它的设计遵循了Unix哲学——“做一件事，并做好”。它提供了一组原子化的子命令：

• mem fact/soul/log 用于 写入 记忆。
• mem search/query 用于 读取和查询 记忆。
• mem status/export/import 用于 维护 记忆。

这个CLI不仅供AI助手在后台调用（例如，AI在对话中识别到需要保存的信息，就会执行 mem fact ... ），也允许开发者直接从终端手动管理记忆。比如，你可以快速输入 mem fact projects my_project “deadline is next Friday” 来记录一个项目截止日期，或者用 mem search “deadline” 来查找所有相关记录。这种设计赋予了系统极大的灵活性。

第三层：SQLite数据库（存储层）。 如前所述，这是数据的最终归宿。其表结构设计简洁而实用：

• facts 表是核心，用于存储结构化的“事实”，采用 (category, subject, content) 的三元组形式，便于组织和检索。
• soul 表存储交互“灵魂”（偏好），如对话风格、输出格式偏好等。
• daily_logs 表按日期记录流水日志，适合记录会话中的关键事件。
• embeddings 表是为 facts 内容存储的向量嵌入，用于支持语义搜索。

这种分层架构使得系统易于理解和维护。自动化层负责无缝集成，交互层提供控制能力，存储层保证数据持久化。

2.3 语义搜索的优雅降级策略

“语义搜索”是 agent-memory 的一个亮点功能。简单来说，当你使用 mem search “前端负责人喜欢Rust” 进行搜索时，系统会尝试理解这句话的 语义 ，而不仅仅是匹配关键词“前端”、“Rust”，从而找到“people / alice: frontend lead, loves Rust”这样的相关记录。

其实现依赖于Google的Gemini Embedding API。当保存一条 fact 时， mem CLI会（如果配置了API密钥）调用该API，将 content 字段的文本转换为一个高维向量（即“嵌入”），并存入 embeddings 表。搜索时，将查询语句也转换为向量，然后在数据库中进行向量相似度计算（通常是余弦相似度），找出最相关的几条 fact 记录。

实操心得 ：这里设计了一个非常巧妙的“优雅降级”机制。如果用户没有配置Gemini API密钥（在 ~/.agent-memory/.env 中设置 GEMINI_API_KEY ）， mem search 会自动回退到基于关键词的简单文本匹配。这意味着 核心的记忆存储和检索功能完全不受影响 ，你只是失去了更智能的语义搜索能力。这种设计极大地降低了使用门槛，用户可以先体验核心功能，再决定是否需要升级到语义搜索。对于许多场景，基于分类和主题的关键词搜索已经足够有效。

3. 核心功能解析与实操要点

3.1 记忆的三种类型：Facts, Soul 与 Logs

agent-memory 将记忆分为三类，这种分类源于对AI协作场景的深刻观察，每种类型服务于不同的目的。

1. Facts（事实）：结构化的长期知识 这是记忆系统的骨架。它采用 (category, subject, content) 的三级结构，强制进行有条理的信息存储。

• Category（类别） ：定义信息的领域，如 people （人物）、 projects （项目）、 decisions （决策）。这相当于文件系统的文件夹，是最高级的过滤维度。
• Subject（主题） ：在类别下的具体条目，如 people 类别下的 alice ， projects 类别下的 website_redesign 。它必须是唯一的（在同一类别内），这保证了信息的可更新性。
• Content（内容） ：具体的描述信息。内容应尽量简洁、客观、包含关键信息。

使用场景示例 ：

# 记录同事信息
mem fact people alice “前端负责人，精通React和TypeScript，对性能优化有深入研究”
# 记录项目关键信息
mem fact projects api_gateway “采用Kong作为网关，认证方式为JWT，部署在K8s的prod命名空间”
# 记录技术决策
mem fact decisions database “从MongoDB迁移至PostgreSQL，因需要更强的事务一致性，迁移截止日期Q3”

注意事项 ： subject 的命名要有辨识度且稳定。避免使用“那个新项目”、“我的经理”这种模糊的指代。好的 subject 如 project_ecommerce_v2 、 manager_sarah ，差的 subject 如 new_project 、 boss 。这能保证后续搜索和引用的准确性。

2. Soul（灵魂/偏好）：个性化的交互设定 如果说 facts 是关于“世界”的知识，那么 soul 就是关于“你”和“你希望AI如何与你互动”的知识。它存储的是交互偏好和元认知。

• Aspect（方面） ：描述偏好的维度，如 tone （语气）、 format （格式）、 focus （关注点）。
• Content（内容） ：具体的偏好描述。

使用场景示例 ：

# 设定对话语气偏好
mem soul tone “偏好直接、简洁的回答，避免冗长的客套和背景介绍”
# 设定代码风格偏好
mem soul code_style “写TypeScript时使用严格的ESLint规则，函数优先使用箭头函数，接口命名以I开头”
# 设定安全边界
mem soul security “切勿在代码示例或解释中提及任何内部服务器IP、域名或API密钥格式”

实操心得 ： soul 的设置至关重要，它能显著提升AI输出的质量。例如，设置了 code_style 后，AI在生成代码片段时会自动遵循你的习惯，减少后续格式化的工作。建议在项目开始时，花几分钟通过 soul 命令将你的核心工作偏好“告诉”AI，这会在长期的协作中节省大量时间。

3. Daily Logs（日志）：会话流水账 日志用于记录临时性的、与时间强相关的会话活动。它不像 facts 那样追求永久性，而是为当天的对话提供上下文。

• 通常由AI助手在会话中自动调用 mem log 来记录，例如：“用户开始调试登录模块”、“用户决定重构用户服务API”。
• 这些日志会在每天结束时（或次日）被新的日志覆盖（取决于实现），主要服务于短期上下文连贯性。

3.2 语义搜索的实现与优化

语义搜索功能是将记忆系统从“简单数据库”升级为“智能助手”的关键。下面深入其实现细节和优化点。

实现流程：

1. 嵌入生成（写操作） ：当执行 mem fact ... 时，CLI会检查是否配置了Gemini API密钥。如果有，则调用 gemini-embedding-2-preview 模型（或其他配置的模型）的API，将 content 文本转换为一个1536维的浮点数向量（嵌入）。这个向量捕获了文本的语义信息。随后，CLI将这条 fact 的 id 和对应的向量（通常序列化为JSON字符串或二进制）存入 embeddings 表。
2. 向量存储 ：SQLite本身并不原生支持向量运算。项目 likely 采用了一种实用方法：将向量以文本（如JSON数组）或二进制BLOB格式直接存储在 TEXT 或 BLOB 字段中。在进行搜索时，需要将全部或部分向量加载到内存中进行计算。
3. 相似度计算（读操作） ：当执行 mem search “查询语句” 时：
   • 首先，将查询语句通过同样的Gemini Embedding API转换为查询向量。
   • 然后，从 embeddings 表中取出所有或部分事实的向量（为了提高性能，可能会只计算最近或特定类别的事实）。
   • 接着，在内存中计算查询向量与每个事实向量之间的 余弦相似度 。余弦相似度的值在-1到1之间，越接近1表示语义越相似。
   • 最后，按相似度得分降序排列，返回得分最高的事实内容。

性能优化考量：

• 缓存策略 ：对于频繁搜索的场景，可以考虑在内存中缓存热点 facts 的向量，避免每次搜索都从数据库读取和反序列化。
• 限制搜索范围 ： mem search 可以结合 category 或近期时间进行过滤，减少需要计算相似度的向量数量。例如，在项目上下文中搜索时，可以优先在 projects 和 decisions 类别中查找。
• 近似最近邻搜索 ：如果记忆库变得非常庞大（例如数万条），线性扫描计算所有向量的相似度会变慢。未来可以考虑集成轻量级的ANN（近似最近邻）库，但会引入额外依赖，与项目的“零依赖”哲学相悖。目前来看，个人开发者的记忆条目数量远未达到需要ANN的程度。

使用技巧 ：

• 搜索时使用 自然语言短语 比使用 关键词 效果更好。例如，搜索“我们怎么处理用户认证？”比搜索“认证”更能找到关于“JWT”、“OAuth”、“登录流程”等相关事实。
• 如果语义搜索返回的结果不理想，可以回退到使用 mem query 执行精确的SQL查询，例如 mem query “SELECT * FROM facts WHERE content LIKE ‘%JWT%’” 。

3.3 与各类AI助手的集成实战

agent-memory 的强大在于其广泛的适配性。以下是针对不同助手的集成要点和避坑指南。

Claude Code（集成度最高） 这是体验最完美的组合。通过 npm install 或 install.sh 脚本可以完成全自动配置。

• 钩子 ：自动修改 ~/.claude/settings.json ，实现上下文自动注入。
• 技能 ：自动安装 agent-memory 技能包。这个技能包至关重要，它“教育”Claude Code理解记忆系统的能力、命令以及 何时应该主动使用记忆 。例如，当Claude检测到你在介绍新同事或做出重要技术决策时，它会主动询问：“需要我将此信息保存到记忆库中吗？”或直接执行 mem fact 命令。
• 检查 ：安装后，可以在Claude Code中直接输入 /skills 查看已安装技能，确认 agent-memory 在列。

Cursor / Windsurf（基于规则的集成） 由于这些IDE插件通常没有公开的钩子API，集成需要一些手动步骤。

1. 创建上下文文件 ：按照指南，在shell配置文件中添加 alias refresh-memory=‘mem-context-hook < /dev/null > .agent-memory-context.md 2>/dev/null’ 。每次开始重要工作前，在项目根目录执行一次 refresh-memory ，生成包含最新记忆的Markdown文件。
2. 创建规则文件 ：
   • 对于Cursor，在项目根目录创建 .cursor/rules/memory.mdc 。
   • 对于Windsurf，在项目根目录创建 .windsurfrules 。
3. 规则内容 ：规则文件必须明确指示AI去读取 .agent-memory-context.md 文件，并告知其可以使用 mem 系列命令。 关键点 ：规则中要说明， 在保存了新记忆后，需要手动再次执行 refresh-memory 命令来更新上下文文件 ，否则本次会话中AI看到的还是旧上下文。

踩坑记录 ：最初我忘记在规则中强调“保存后需刷新”，导致AI记住了新信息，但后续对话的上下文注入中却没有体现，造成了混乱。务必在规则中清晰写出这个步骤。

Aider（通过包装脚本或配置集成） Aider支持 --read 参数和 system-prompt-extras 配置。

• 推荐方法（包装脚本） ：创建 aider-mem 脚本。这个脚本的妙处在于，它每次启动Aider时都会 动态生成 一个全新的、包含最新记忆的临时上下文文件。这确保了记忆的实时性，无需手动刷新。

  #!/usr/bin/env bash
  CONTEXT_FILE=$(mktemp /tmp/memory-context.XXXXXX.md)
  # 生成记忆上下文，错误输出静默
  mem-context-hook < /dev/null > “$CONTEXT_FILE” 2>/dev/null
  # 将上下文文件和其他参数传递给aider
  aider --read “$CONTEXT_FILE” “$@”
  # 清理临时文件
  rm -f “$CONTEXT_FILE”
  

  记得给脚本加执行权限： chmod +x aider-mem ，然后就可以用 ./aider-mem 代替原来的 aider 命令了。
• 备选方法（修改配置） ：在 .aider.conf.yml 中增加 system-prompt-extras 。这种方法更简单，但缺点是提示词长度可能有限制，且记忆上下文不是结构化的块，可能影响AI的理解。

通用法则 ：对于任何其他能执行Shell命令的AI助手，你只需要在其系统指令（System Prompt）或规则文件中添加 mem 命令的使用说明，并手动或自动地在对话前执行 mem-context-hook 来获取上下文。核心就是两点： 教会AI如何使用命令 ，以及 确保AI在回复前能接收到记忆上下文 。

4. 实战部署与日常使用工作流

4.1 从零开始：安装与初始化最佳实践

虽然 npm install -g 是最快的方式，但通过 git clone 安装能让你更了解系统构成，也便于后续贡献或自定义修改。

步骤一：克隆与安装

git clone https://github.com/OctavianTocan/agent-memory.git
cd agent-memory
# 在执行安装脚本前，建议先检查依赖
python3 --version # 确保 >= 3.9
which sqlite3 # 确保SQLite命令存在
# 执行安装
./install.sh

install.sh 脚本会完成以下几件事，你可以打开脚本查看其具体逻辑：

1. 在你的家目录下创建 ~/.agent-memory/ 数据目录。
2. 将 memory.db 数据库文件初始化在该目录下（运行 mem init ）。
3. 将 bin/ 目录下的 mem 和 mem-context-hook 等核心脚本软链接到 ~/.local/bin/ （确保该目录在你的 PATH 环境变量中）。
4. 如果检测到 ~/.claude 目录，会自动配置Claude Code的钩子和技能。
5. 如果检测到 ~/.gemini 目录，会自动配置Gemini CLI的钩子。

步骤二：配置语义搜索（可选但推荐）

1. 前往 Google AI Studio 获取一个免费的Gemini API密钥。
2. 编辑 ~/.agent-memory/.env 文件（如果不存在，从项目根目录复制 .env.example ）：

   cp agent-memory/.env.example ~/.agent-memory/.env
   nano ~/.agent-memory/.env
   

3. 在文件中填入你的API密钥：

   GEMINI_API_KEY=your_actual_api_key_here
   

   安全提示 ： .env 文件包含敏感信息。确保其权限为 600 （仅所有者可读写）： chmod 600 ~/.agent-memory/.env 。切勿将其提交到版本控制系统。

步骤三：验证安装

# 验证CLI是否可用
mem status
# 预期输出类似：Database: /Users/you/.agent-memory/memory.db, Facts: 0, Soul entries: 0, Logs today: 0
# 手动添加一条记忆测试
mem fact test verification “agent-memory is working”
mem search “working”
# 如果配置了API密钥，应能搜到上一条；如果未配置，使用关键词‘working’也应能搜到。

4.2 构建你的初始记忆库：引导式录入

安装完成后，一个空的记忆库价值有限。你需要主动“喂养”它。以下是一个高效的初始录入策略，建议按顺序进行：

第一阶段：录入个人与工作核心信息（Soul + Facts） 这些是AI理解你背景的基础。

# 1. 设定你的交互灵魂（Soul）
mem soul tone “回答请直接切入主题，无需问候和总结。解释技术概念时请附带简短示例。”
mem soul code_output “代码块请使用明确的语法高亮语言标记，如 ```python。除非特别要求，否则优先给出代码而非文字描述。”
mem soul security “绝对不要生成或讨论任何涉及网络代理、绕过网络限制或相关工具的内容。”

# 2. 录入关于你自己的事实（Facts）
mem fact user_info myself “全名：[你的名字]，居住城市：[城市]，时区：[UTC+8]”
mem fact work employer “[公司名]”
mem fact work role “[你的职位，如高级后端工程师]”
mem fact work tech_stack “主要语言：Go, Python；熟悉框架：Gin, Django；数据库：PostgreSQL, Redis；云平台：AWS”
mem fact preferences editor “主用VS Code，配色主题：One Dark Pro，常用插件：GitLens, Docker, Remote - SSH”

第二阶段：录入当前项目上下文（Facts） 如果你正在进行的项目会频繁与AI讨论，那么录入项目细节能极大提升效率。

# 假设你正在开发一个叫‘OctoShop’的电商项目
mem fact projects octoshop “一个基于微服务的电商平台，当前处于v1.2开发阶段，核心团队5人。”
mem fact projects octoshop_tech “后端：Go微服务，gRPC通信，PostgreSQL，Redis缓存，K8s部署。前端：Next.js 14, Tailwind CSS。”
mem fact decisions octoshop_auth “用户认证已决定采用JWT，令牌有效期24小时，刷新令牌有效期7天。”
mem fact decisions octoshop_deploy “生产环境部署在AWS EKS，CI/CD使用GitLab Runner，部署冻结窗口为每周五。”
mem fact people project_manager “Alice，负责项目管理和客户沟通，偏好每日站会同步进度。”
mem fact people tech_lead “Bob，负责后端架构，代码审查严格，强调测试覆盖率。”

第三阶段：测试与验证 录入完成后，进行搜索测试，确保信息能被准确召回。

mem search “我用的编程语言”
# 应返回 work / tech_stack 相关内容
mem search “电商项目用什么认证”
# 应返回 decisions / octoshop_auth 相关内容
mem search “谁管项目进度”
# 应返回 people / project_manager 相关内容

4.3 日常使用模式：主动保存与被动调取

记忆系统融入工作流后，会形成两种主要使用模式：

1. 主动保存（由你或AI触发）

• 你手动保存 ：在终端中直接使用 mem 命令。适合记录明确的、离散的信息。

  # 开会后记录决策
  mem fact decisions meeting_20240415 “决定将用户头像存储从本地迁移到S3，由David负责，两周内完成。”
  # 遇到一个有用的技术方案
  mem fact knowledge react_optimization “大型列表渲染使用虚拟滚动库（如react-window），并配合React.memo避免不必要的子组件重渲染。”
  

• AI主动询问并保存 ：得益于Claude Code的技能，AI会在对话中识别到可能值得保存的信息，并主动询问。你应该积极同意。这是让AI学习你模式的最佳方式。

  用户 ：“我们这次把错误日志从文件改成了发送到Elasticsearch集群，方便追踪。” Claude Code ：“这听起来像是一个重要的架构变更。需要我将‘错误日志改用Elasticsearch’这个信息保存到您的记忆库中吗？（我可以使用命令： mem fact decisions logging “将应用错误日志从本地文件改为集中发送至Elasticsearch集群，便于分布式追踪和分析。” ）” 用户 ：“好的，保存吧。”

2. 被动调取（由钩子自动注入） 这是系统的核心自动化能力。你无需做任何事，每次对话开始，相关的 facts 、 soul 和当日的 logs 会自动出现在AI的“脑海”里。你会发现在后续对话中，AI不再问你“你是做什么的？”，或者会基于已知的技术栈给出更精准的建议。

3. 主动查询（当你需要时） 当你在复杂讨论中需要追溯某个具体信息时，可以直接在AI对话中或终端里查询。

• 在AI对话中 ：你可以直接要求AI帮你查。“查一下我们之前关于数据库分库的决策是什么？” AI可以执行 mem search “数据库分库” 来找到相关记录。
• 在终端中 ：使用 mem search 或更精确的 mem query 。

  # 模糊搜索
  mem search “AWS 配置”
  # 精确SQL查询（如果你熟悉表结构）
  mem query “SELECT * FROM facts WHERE category=‘decisions’ AND content LIKE ‘%S3%’ ORDER BY updated_at DESC”
  

4.4 维护与备份策略

记忆库会随着时间增长，合理的维护能保证其长期有效性。

1. 定期清理与更新

• 更新过时信息 ：使用 mem fact 命令重复相同的 category 和 subject 会自动更新内容（基于 UNIQUE 约束）。

  mem fact work role “从高级后端工程师晋升为技术专家”
  

• 归档或删除无用信息 ：对于已完结的项目或失效的决策，可以考虑将其 category 改为 archive ，或者直接通过SQL删除。

  mem query “DELETE FROM facts WHERE category=‘projects’ AND subject=‘old_legacy_system’”
  

  注意 ：删除操作不可逆，请谨慎执行。建议先使用 SELECT 语句确认要删除的内容。

2. 数据备份与迁移 你的记忆库是宝贵的数字资产，应定期备份。

• 轻量级备份（仅数据） ： mem export 命令将 facts 和 soul 表导出为JSON，不包含向量嵌入，文件很小。

  mem export > ~/backups/agent_memory_$(date +%Y%m%d).json
  

• 完整备份（包含向量） ： mem dump 命令导出整个数据库的完整副本，包括 embeddings 表，文件较大。

  mem dump ~/backups/agent_memory_full_$(date +%Y%m%d).json
  

• 迁移到新机器 ：
  1. 在新机器上安装 agent-memory 。
  2. 将备份的JSON文件复制到新机器。
  3. 执行导入（使用 --force 会先清空现有数据库）：

     mem import ~/backups/agent_memory_full_20240415.json --force
     

3. 状态监控 使用 mem status 随时查看记忆库的健康状况和数据统计。

5. 常见问题排查与进阶技巧

5.1 安装与集成问题排查

问题1：安装后， mem 命令未找到。

• 原因 ： install.sh 脚本将可执行文件软链接到了 ~/.local/bin/ ，但该目录可能不在你的 PATH 环境变量中。
• 解决 ：

  # 检查链接是否存在
  ls -la ~/.local/bin/mem
  # 检查PATH
  echo $PATH | grep ‘.local/bin’
  # 如果不在，将以下行添加到你的 ~/.bashrc 或 ~/.zshrc
  export PATH=“$HOME/.local/bin:$PATH”
  # 然后重新加载配置
  source ~/.bashrc # 或 source ~/.zshrc
  

问题2：Claude Code没有自动注入记忆上下文。

• 原因1 ：钩子配置未成功写入 ~/.claude/settings.json 。
• 排查 ：检查该文件，查看 hooks 部分是否包含指向 mem-context-hook 的 UserPromptSubmit 命令。
• 解决 ：可以手动编辑 settings.json 添加，或重新运行 ./install.sh 。
• 原因2 ： mem-context-hook 脚本本身执行出错。
• 排查 ：在终端手动运行该脚本看是否有错误输出。

  mem-context-hook < /dev/null
  

  • 如果提示数据库错误，可能是 ~/.agent-memory/memory.db 文件权限问题。
  • 如果提示Python模块错误，请确保使用Python 3.9+。
• 解决 ：根据错误信息修复，例如 chmod 755 ~/.agent-memory 确保目录可执行，或重装Python依赖。

问题3：语义搜索（ mem search ）返回“Keyword fallback activated”。

• 原因 ：未配置Gemini API密钥，或配置的密钥无效、网络无法访问API。
• 排查 ：

  # 检查.env文件是否存在且包含有效密钥
  cat ~/.agent-memory/.env
  # 测试API连通性（假设你有curl和jq）
  API_KEY=$(grep GEMINI_API_KEY ~/.agent-memory/.env | cut -d= -f2)
  curl -s -X POST “https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2-preview:embedContent?key=$API_KEY” \
  -H ‘Content-Type: application/json’ \
  -d ‘{“content”: {“parts”:[{“text”: “test”}]}}’ | jq .
  

  • 如果返回 403 或 404 错误，说明密钥无效或格式错误。
  • 如果请求超时，可能是网络问题。
• 解决 ：确认密钥正确，检查网络，或暂时接受关键词回退模式。

5.2 使用中的典型问题

问题1：AI助手似乎“忘记”了刚刚保存的信息。

• 原因 ：记忆上下文是在 每条消息发送前 动态生成的。如果你在同一个会话中保存了新记忆，但后续提问前没有触发上下文更新，AI就看不到新内容。
• 解决 ：
  • 对于Claude Code/Gemini CLI（自动钩子）：通常在下一条消息发送时，钩子会重新运行并包含新记忆。如果没有，可以尝试发送一条空消息或刷新会话。
  • 对于Cursor/Windsurf（文件方式）：你需要手动在终端执行一次 refresh-memory 别名命令来更新 .agent-memory-context.md 文件，并 确保AI助手重新读取了该文件 （有时需要重启AI对话或重新打开文件）。
  • 最佳实践 ：重要的新记忆保存后，可以在对话中加一句提示：“请记住，我们刚刚决定采用X方案。” 这既能提醒AI，也能触发其内部可能的重读上下文机制。

问题2： mem search 返回的结果不相关或太多。

• 原因 ：搜索查询太宽泛，或者语义搜索的相似度阈值设置问题（如果项目可配置）。
• 解决 ：
  • 优化查询 ：使用更具体、包含更多实体的自然语言句子。例如，用“我们电商项目的用户认证方案”代替“认证”。
  • 结合分类过滤 ：如果知道信息的大致类别，可以先通过 category 缩小范围。目前CLI不支持直接组合过滤，但可以通过 mem query 实现：

    mem query “SELECT * FROM facts WHERE category=‘decisions’ AND content LIKE ‘%认证%’”
    

  • 审视记忆质量 ：检查保存的 content 是否足够清晰、包含关键信息。模糊的记录（如“用了那个新框架”）很难被有效检索。

问题3：数据库文件（ memory.db ）越来越大。

• 原因 ： embeddings 表存储的向量数据占用空间较大（每条记录约几十KB）。
• 解决 ：
  • 定期清理无用记忆 ：如前所述，归档或删除过期项目。
  • 考虑禁用语义搜索 ：如果空间紧张且关键词搜索已够用，可以删除 .env 中的API密钥，系统将不再生成和存储嵌入向量。注意，这不会删除已存在的向量，但会停止新增。要清理旧向量，需要执行SQL： mem query “DELETE FROM embeddings” 。
  • SQLite维护 ：可以定期对数据库执行 VACUUM 命令来回收空间（ 操作前请备份 ）。

    sqlite3 ~/.agent-memory/memory.db “VACUUM;”
    

5.3 进阶技巧与自定义

1. 自定义记忆类别（Categories） 项目建议了一些默认类别（ user_info , people , projects 等），但你可以完全自定义。选择对你和你的项目有意义的分类体系。例如，增加 bugs （记录遇到的棘手bug和解决方案）、 learning （学到的知识点）、 meetings （会议纪要要点）等。

2. 利用 mem query 进行高级操作 mem query 是你的瑞士军刀，可以执行任何SQLite支持的SQL语句。

• 批量操作 ：

  # 将某个分类下的所有subject加上前缀
  mem query “UPDATE facts SET subject=‘old_’ || subject WHERE category=‘archive’”
  # 查找并删除所有空内容或测试内容
  mem query “DELETE FROM facts WHERE content=‘test’ OR content IS NULL OR trim(content)=’’”
  

• 数据分析 ：

  # 查看最常更新的记忆类别
  mem query “SELECT category, COUNT(*) as count, MAX(updated_at) as last_updated FROM facts GROUP BY category ORDER BY count DESC”
  # 查找超过30天未更新的陈旧记忆
  mem query “SELECT * FROM facts WHERE julianday(‘now’) - julianday(updated_at) > 30”
  

3. 为其他工具创建别名或包装脚本 你可以创建更便捷的别名来快速记录。

# 添加到 ~/.bashrc 或 ~/.zshrc
alias remember=‘mem fact’
alias whatwas=‘mem search’
alias howdo=‘mem soul’
# 快速记录日志
alias did=‘mem log’

现在，在终端里你可以直接输入：

remember decisions design_system “决定采用原子设计方法论”
whatwas “设计系统”
howdo code_review “提交PR时，请在描述中附上测试覆盖率和性能影响分析”
did “完成了用户登录模块的重构”

4. 探索数据库直接操作（谨慎！） 对于高级用户，可以直接用 sqlite3 命令行工具打开数据库文件进行查看或紧急修复。

sqlite3 ~/.agent-memory/memory.db
.tables
SELECT * FROM facts LIMIT 5;

重要警告 ：直接操作数据库有风险，可能破坏数据一致性。尤其是 embeddings 表与 facts 表有外键关联。非必要不直接操作，优先使用 mem CLI。