mimirs：给 AI coding agent 一份可搜索的项目记忆
AI coding agent 最耗上下文的地方，往往不是写那几行补丁，而是每次重新理解项目：文件在哪里、某个概念叫什么、测试入口有哪些、上次为什么绕开了某条路。人类开发者会在脑子里留下这些项目记忆，agent 则经常在新 session 里重新 grep、重新读 README、重新猜目录结构。
这类问题不一定要靠更大的 context window 解决。更务实的办法，是给每个项目留一份本地、可更新、可搜索的记忆层：把代码片段、符号关系、wiki、conversation history 和人工标注放在离仓库很近的位置，让 agent 需要时再取。
今天看的是 TheWinci/mimirs。它是一个面向 AI coding agents 的本地 MCP server 和 CLI，用 Bun、SQLite、sqlite-vec、semantic search、AST-aware chunking、dependency graph、conversation history 来保存项目上下文。README 里的定位很直接：persistent project memory for AI coding agents，一条命令设置，之后尽量少维护。它支持 Claude Code、Cursor、Windsurf、JetBrains Junie、GitHub Copilot，以及任何能接 stdio MCP server 的客户端；Codex 也可以通过 ~/.codex/config.toml 手动接入。
按 GitHub repository API、README、LICENSE、Releases 页面、Tags 页面、package.json 和最近 commit 在 2026-08-16 能核验的公开信息，TheWinci/mimirs 当前有 29 stars、2 forks。仓库主语言是 TypeScript，GitHub repository API 和 package.json 都标记许可证为 Apache-2.0，LICENSE 文件也是 Apache License 2.0 文本。仓库创建于 2026-03-16 22:51:00 UTC，最近公开 push 是 2026-08-15 09:23:55 UTC，默认分支是 main。GitHub Releases 页面显示目前 没有正式 Release；Tags 页面最新 tag 是 v1.7.1，日期 2026-06-22。main 分支当前 package.json 版本是 1.8.0，最近 commit 是 8c11a54，提交信息为 1.8.0，commit 时间 2026-08-15 11:21:41 +02:00。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | TheWinci/mimirs |
| 定位 | 给 AI coding agent 使用的本地项目记忆和代码检索 MCP server |
| Stars | 29 |
| Forks | 2 |
| 主要语言 | TypeScript |
| 许可证 | Apache-2.0 |
| 创建时间 | 2026-03-16 22:51:00 UTC |
| 最新 push | 2026-08-15 09:23:55 UTC |
| 默认分支 | main |
| GitHub Releases | 暂无正式 Release |
| 最新 tag | v1.7.1，2026-06-22 |
| 当前 package 版本 | 1.8.0 |
| 最近 commit | 8c11a54，1.8.0 |
| 关键词 | MCP、semantic search、SQLite、local-first、agent memory、code graph |
它解决的是“每个 session 都从零开始”
mimirs 的切入点不是替代 IDE，也不是做一个通用向量数据库。它更像是把 agent 反复做的仓库侦察动作沉淀下来：先索引项目，再提供 search、read、project map、dependency graph、annotation、conversation search 这类工具，让 agent 在写代码前能快速拿到相关文件和过去上下文。
README 里有一个很典型的描述：agent 每次开始都像是失明一样猜文件名、用关键字搜索、烧上下文、忘记昨天讨论过的东西。mimirs 的回答是把这些东西留在本地 SQLite 里，通过 MCP 暴露给 agent。它不是让模型一次性吞下全仓库，而是让模型提出更小的问题，再从索引里拿回更相关的片段。
这对中大型代码库尤其有用。很多修复其实不难，难的是先找到“真正该改哪里”。如果 agent 每次都从 ls、find、grep auth 开始，前几轮对话都会浪费在探索上。mimirs 把这种探索变成项目级缓存：文件、chunk、symbol、调用关系、会话记录都可以逐步积累。
本地优先，比 SaaS 记忆更适合代码库
这个项目的一个重要取舍是本地优先。README 明确强调不需要 API key、不需要云服务、不需要 Docker，核心依赖是 Bun 和 SQLite。索引默认放在项目的 .mimirs/ 目录；如果仓库是只读挂载，也可以用 RAG_DB_DIR 把索引放到可写位置。
这类设计对代码库上下文很重要。团队可能愿意把公开 issue 发给模型，却未必愿意把整个私有仓库、历史讨论、临时标注都交给外部记忆服务。mimirs 不能替你解决所有模型调用的数据边界，但至少把项目记忆层留在本机，减少了“为了让 agent 记住项目，就必须引入一个云端知识库”的压力。
它也比较贴近实际编辑器生态。README 给了 Claude Code、Cursor、Windsurf、JetBrains Junie、GitHub Copilot 的 MCP 配置片段，也给了 Codex 的 TOML 示例。最短路径是：
bunx mimirs init --ide claude
bunx mimirs index
bunx mimirs status如果不想用自动初始化，也可以只把 stdio MCP server 接进客户端：bunx mimirs@^1 serve，再通过 RAG_PROJECT_DIR 指向项目根目录。这个形态很适合先在一个非关键仓库里试，不需要改服务端架构。
搜索之外，还有 wiki、图谱和会话记忆
mimirs 最容易理解的功能是 semantic search，但它不只是在文件上套一个 embedding。package.json 和 README 里都能看到它的范围：AST-aware chunking、dependency graphs、conversation history、project wiki、annotation、affected tests、symbol usage 等。也就是说，它试图把“agent 需要知道项目什么”拆成几类不同工具，而不是把所有问题都压进一个相似度搜索框。
这很关键。代码搜索并不总是“找最像的文本”。有时你要知道一个函数的调用者，有时要找某个模块影响哪些测试，有时要把上次 session 的结论捞出来，有时只是要一份项目结构摘要。mimirs 通过 MCP 工具把这些入口分开，agent 就不必把所有问题都翻译成普通 grep。
README 还列了几组 benchmark，包括在 Django、Kubernetes、Excalidraw、mimirs 自身上的 Recall@10、MRR 等结果。博客里不需要把这些数字当成独立第三方结论，但它说明作者在认真看检索质量，而不只是做一个“把代码塞进向量库”的 demo。
Caveats
第一，mimirs 现在仍然是很小的项目。29 stars、2 forks，GitHub Releases 页面也还没有正式 release；虽然 package.json 已经到 1.8.0，Tags 页面最新 tag 仍停在 v1.7.1。生产团队要把它接到日常 agent workflow 之前，应该先接受版本节奏可能很快、接口可能继续变化。
第二，它依赖 Bun 和 SQLite extension。对个人开发机这不复杂，但在受控企业环境、远程 dev container、Windows/macOS 混合团队里，Bun 路径、SQLite 版本、编辑器从 GUI 启动时的 PATH，都会变成真实兼容性问题。README 里专门解释了 bunx 在 GUI 编辑器里找不到的情况，这不是理论风险。
第三，记忆系统也会产生维护成本。过期的 annotation、旧 conversation、错误索引、被删除的文件关系，如果不清理，可能会误导 agent。mimirs 提供了索引和 wiki 更新路径，但团队仍然要决定哪些内容可以长期保留，哪些应该随分支或任务结束清掉。
总结
TheWinci/mimirs 有意思的地方，是它没有把 agent 记忆做成一个抽象口号，而是落在了本地项目工作流里：Bun 启动、SQLite 存储、MCP 暴露工具、编辑器直接接入。它承认 agent 需要的不是无限上下文，而是一组能反复查询、能逐步沉淀的项目线索。
如果你已经在 Claude Code、Cursor、Windsurf、Codex 或自建 MCP client 里频繁让 agent 改同一个代码库，mimirs 值得试在一个中等规模仓库上。它最适合的场景不是“让模型记住所有事情”，而是减少每个 session 的冷启动成本：少猜文件，少重复读文档，多把注意力放在真正要改的代码上。