用途
agmem 为编程智能体提供持久化、与源码关联的项目记忆。它解决的核心问题是：智能体每次会话都要重新 grep 同一个仓库，而 CLAUDE.md、AGENTS.md、.cursor/rules/ 等静态规则文件无法反映不断变化的代码库。agmem 把仓库索引成可查询的本地存储，让智能体在每次任务中快速取回相关上下文。
主要能力
- 索引：
agmem index遍历仓库（遵循 .gitignore），提取 Terraform 资源、模块、变量、输出；Python 类、顶层函数、FastAPI 风格路由；Go 类型、函数、方法、chi/gin/echo HTTP 路由；YAML/Helm 值（展平为可搜索的点分键路径）；Markdown 章节（长文档按 H2 拆分）及 PRD 状态。 - 检索：
agmem context "<task>"返回按 BM25 + 词法别名排序的任务相关片段，分组为 Constraints / Facts / Patterns，每条带 source_ref 和 commit。查询建议使用标识符密集的名词片段（如waf-alb-public storefront ingress-gateway-external count），而非完整句子。 - 规则记忆：对索引器无法推断的内容（团队约定、"不要再做 X"），可用
agmem remember "..." --kind rule写入，规则在检索中获得 4 倍分数加成。 - 会话模式：多查询工作流可加
--session，后续调用会降权已看过的结果、提升已读文件的兄弟章节，并给出"尚未看到"提示。 - Git 感知：post-merge 钩子让记忆在队友推送后保持同步；post-commit、post-rewrite 钩子跟随本地提交。
- 漂移追踪：每条记录携带 source_hash + source_commit，可验证来源。
- 性能：数千条记录的存储上搜索低于 100ms。
使用方式
支持任何能执行 shell 命令的智能体（Claude Code、Codex、opencode、Cursor、Aider）。安装约 60 秒。Claude Code 集成最深，可通过插件自动在每次提示时注入任务相关上下文，并附带 agmem 技能与 /agmem:setup 命令；也可手动接入，向 CLAUDE.md 添加幂等块、UserPromptSubmit 钩子及三个 git 钩子。Codex/opencode（AGENTS.md）、Cursor（.cursor/rules/）、Aider 或自定义 CI 脚本参见智能体集成指南。
适用场景
- 需要跨会话记住代码库结构的编程智能体工作流。
- 希望上下文检索完全本地、无 API 调用、无 SaaS 依赖的团队。
- 需要追踪记忆与源码漂移、可验证来源的场景。
限制
- 处于 Alpha 阶段，自 2026 年 4 月起在真实仓库日常使用，1.0 之前 API 可能在小版本间变化。
- 已在 macOS 和 Linux 测试；Windows 为尽力支持：包可导入、核心命令可运行，但文件锁退化为空操作（假定单写入者），且尚未纳入 CI。
- 默认安装无重型依赖；可选的 [hybrid] 扩展会引入 sentence-transformers，安装 PyTorch（约 2 GB）并在首次使用时下载 90 MB 嵌入模型。
- 不进行微调、不要求守护进程或服务器、不依赖 MCP、不将任何内容存入云端。
- 基准测试 LongMemEval 衡量的是对话历史检索而非代码检索；agmem 的主要用途是代码记忆。
