memgit

memgit — AI 记忆的 git

会话结束后，你的 AI 助手就会忘记一切。memgit 可以解决这个问题。

受版本控制、跨 AI 共享的上下文，能够像代码一样持久保存、生成差异、回滚和同步。在项目进行到一半时从 Claude 切换到 Cursor 或 ChatGPT——你的上下文已经就绪。

---

为什么不用 claude.md？为什么不用 mem-search？

你可能已经试过这两种方案。下面说明了它们为何会遇到瓶颈：

功能	claude.md	mem-search 插件	memgit
仅加载相关上下文	❌ 加载全部内容	⚠️ 加载近期观察结果	✅ BM25 搜索——每次查询返回 top-k
在多仓库的长期使用中感知项目	❌ 按文件区分	❌	✅ 记忆带有 project 字段；当前工作区优先排序
应用于现有代码库	❌ 从空白开始	❌ 从空白开始	✅ memgit onboard——一次性从代码库初始化存储
版本历史	❌	❌	✅ 完整提交日志
比较不同会话	❌	❌	✅ memgit diff
回滚错误记忆	❌ 手动编辑	❌	✅ memgit rollback
适用于 Cursor、Windsurf、GPT	❌ 仅限 Claude	❌ 仅限 Claude	✅ 均可通过 MCP / HTTP 使用
团队同步	❌ 复制粘贴文件	❌	✅ memgit git push
可扩展至 10k+ 个会话	❌ 文件不断增大	❌ 搜索变慢	✅ memgit squash
可衡量的 token 节省	❌	❌	✅ memgit stats
导出 / 导入标准格式	❌	❌	✅ TOON + git

---

实证——可衡量的上下文成本

在你自己的存储中运行此命令，查看实际数据（尽可能使用实测值；估算值会标明）：

$ memgit stats

  Total memories:   108   (41 feedback · 23 user · 19 project · 12 reference · 8 convention · 5 lesson)
  Priority:          3 critical · 67 medium · 38 low

  Context footprint  (measured where possible; estimates labeled)

  Surface                                             Tokens
  Full store (every memory as context)                12,840
  Resume digest  (measured render)                       540
  Recall block  (estimate: top-3 rules ≈ chars/4)        ~60

  per-session injected ≈ 600 tokens (estimate) vs 12,840 tokens if the full store were loaded

为什么差别这么大？ claude.md 会在每个会话中加载全部上下文。memgit 注入有上限的恢复摘要，以及通过 BM25 匹配的回忆内容——仅包含与当前会话相关的内容，而不是你记录过的所有内容。摘要大小通过实际渲染测量，存储总量则是实际语料库大小；这里没有模拟基准测试。

---

git 的类比是字面意义上的

memgit 的数据模型与 git 一一对应：

memgit	git
mnemonic	文件
MindState	树
checkpoint	提交
thread	分支
memgit commit	git commit
memgit diff	git diff
memgit log	git log
memgit squash --keep-last 100	git rebase -i --autosquash
memgit git push	git push

这不是比喻——memgit 使用与 git 架构相同的内容寻址对象存储（SHA-256 blob）。每条记忆都有稳定的 SHA。相同内容拥有相同的 SHA。旧状态始终可以恢复。

---

存储本身就是一个 git 仓库

每条记忆都是 memories/ 下一个可读的 .toon 文件。使用标准 git 将整套记忆推送到 GitHub：

memgit git init --remote [email protected]:yourteam/ai-memory.git
memgit git push

队友拉取后，从第 1 个会话开始就能使用 AI 学到的规则：

git clone [email protected]:yourteam/ai-memory.git ~/.claude/memgit-store
memgit setup all

你可以像处理代码一样对记忆使用 grep、git blame 和 git diff：

grep -rl "database" ~/.claude/memgit-store/memories/
git log --follow memories/no-db-mock.toon
git diff HEAD~7 memories/

---

安装

Mac / Linux：

pip install memgit

Mac（Homebrew）：

brew tap code4161/tap && brew install memgit

Windows：

choco install memgit
# or
pip install memgit

（Chocolatey 软件包已在 community.chocolatey.org 上发布；新推送的版本可能需要几天才能通过审核——pip install memgit 始终可获取最新版本。）

任意 AI 工具配置（无需 Python——npx 首次运行时会自动安装）：

{ "mcpServers": { "memgit": { "command": "npx", "args": ["-y", "memgit-mcp"] } } }

---

快速入门（3 分钟）

# 1. Install and initialize
pip install memgit
memgit init               # auto-detects the best location, finds your existing
                          # Claude Code memories, and offers to import them

# 2. Register with your AI tools (interactive picker)
memgit setup

# 3. See your token savings
memgit stats

init 会引导你完成设置——无需查找路径。（之后导入只需运行一个无需参数的命令：memgit sync 会自动查找 ~/.claude/projects/*/memory。）

重启 AI 工具——现在，它会在每个会话开始时搜索你的记忆存储。

---

在项目进行中采用 memgit

记忆工具存在冷启动问题：在项目进行到一半时安装，它就什么都不知道——没有初始起点，上下文只能从未来的会话中逐渐积累。memgit 通过一次性播种来解决这个问题：

cd your-project
memgit onboard          # mines the repo, prints the bootstrap brief

onboard 首先以确定性方式提取仓库摘要——包括 Git 历史记录（近期提交主题、按变更量统计的热门文件／目录、作者、分支、标签）、从清单中检测到的技术栈，以及值得阅读的文档——整个过程使用有界、只读的探测，即使面对超大型仓库也几乎能瞬间完成。随后，简报会准确告知你的 AI Agent 如何处理这些信息：只阅读列出的文件（不遍历目录树），提取 10–20 条持久性事实（用途、架构、约定、当前状态、注意事项），将每条保存为带类型的记忆，并为种子记忆集创建检查点。把它粘贴到会话中即可——也可以不这样做：如果 AI 在没有任何记忆的项目中搜索记忆，MCP 服务本身会回复引导初始化的说明，而不是只说一句“没有结果”。

记忆按项目划分，默认过滤（v0.7.0）：每条记忆都带有所属工作区，搜索、回忆注入和恢复摘要（近期记忆、检查点、深度提示）都会过滤到当前项目系列以及明确设为全局的记忆——其他项目的内容绝不会泄露。可通过 memgit search --all-projects / all_projects: true（此时每条结果都会带有 project 标签）有意扩大范围，也可以用 --project 强制过滤到某个项目。没有项目归属的记忆即为明确的全局记忆（适用于所有项目）：使用 memgit add --global 或 project: "" 即可保存。无法确定所属项目的保存内容绝不会被默默设为全局记忆——它会被隔离到 _unknown 下（在 list 中显示为 [?project]，由 lint 标记，不会出现在任何地方），直到你使用 memgit doctor --relabel 为它重新指定项目。

---

从上次离开的地方继续

在新会话中问 AI “我们能继续处理待办任务吗？”，它就会根据碰巧处于打开状态的文件进行猜测。memgit resume 用记录取代猜测：

memgit resume            # last checkpoints, work in flight, recent + critical memories
memgit resume --plain    # plain text, for piping into an AI context
memgit resume --json     # for tooling

将它接入 Claude Code，让记忆变得自动化——无需调用工具，也无需判断：

memgit setup hooks       # installs all six hooks (~/.claude/settings.json)

Hook	强制执行的内容
SessionStart	每个会话开始时，都会将恢复摘要载入上下文——状态面板、检查点、关键规则、记忆索引
UserPromptSubmit	根据存储内容对每条提示词进行 BM25 匹配；注入相关记忆。如果存在更多相关内容，会以“关于“”的另外 +N 条”深度提示结尾（没有任何内容达到相关性门槛时保持静默；每个会话中不会重复）——使用 --no-recall 可跳过
PreToolUse	如果 Bash 或文件写入调用匹配某条记忆的触发条件，则拒绝该调用，并以规则作为原因（优先级 3 的反馈和约定），或将规则作为上下文提供（其他情况）。运行 memgit allow SLUG 可开启一个短暂的覆盖窗口。仅使用触发条件缓存；使用 --no-gate 可跳过
PostToolUse	如果读取文件的路径与记忆标签匹配，则显示一行提示（“有 6 条带有 'x' 标签的记忆与此路径相关”）——仅使用标签映射缓存，每个会话最多显示 3 次；使用 --no-ctx-recall 可跳过
Stop（守卫）	如果受规则管控的调用绕过守卫执行，或会话执行了实际工作却没有保存任何内容，则会在结束前阻止一次。使用 --no-guard 可跳过
Stop（同步）	会话结束时，异步为 Markdown 记忆创建检查点

为什么要用 Hook，而不只是编写好的工具描述？我们进行了测量：在 166 次真实会话中，Hook 注入的上下文在100% 的会话中成功送达，而主动调用记忆工具的比例只有 6%。Hook 强制执行的内容才会真正发生。

恢复摘要的长度经过刻意限制（在包含 500 条记忆的存储中测得约 350 个 token）：规则会被截断，关键列表设有上限，而完整文本只需调用一次 get_memory 即可获取。

扩展到 10,000+ 个会话

使用数月后，检查点历史记录会不断增长。Squash 可压缩历史记录，gc 可回收磁盘空间：

memgit squash --keep-last 100    # keep last 100 checkpoints, squash everything older
memgit squash --older-than 30    # squash everything older than 30 days
memgit squash --dry-run          # preview first

memgit gc                        # delete unreachable objects, trim reflogs
memgit gc --dry-run              # preview
memgit gc --squash-keep 200      # compact history, then sweep

当前内存状态始终会保留——而且 squash 在实质内容上无损：每个被折叠的检查点都会在 .memgit/logs/archive/ 下的只追加归档中留下一行记录（时间、作者、差异、消息），gc 永远不会触碰该归档。在包含 2,000 个检查点的存储上进行基准测试：空间缩小 94%（39.5 MB → 2.2 MB），fsck 检查通过。随着链条增长，历史记录操作仍保持 O(1)（在 2,000 个检查点时，SHA 解析和检查点计数的测量结果约为 0.08 ms）。

---

多个 Agent，共享一份内存

所有写入操作都通过 git 风格的存储锁进行（开销为 0.08 ms），因此并发运行的 Agent 不会损坏存储，也不会丢失彼此的更新。有两种模式：

共享线程——Agent 并发写入；如果一个 Agent 提交时另一个 Agent 已暂存更改，第二次提交会自动合并（基于记录的基准版本进行三方合并），而不是覆盖。设置 MEMGIT_AUTHOR=agent-name，即可在每个检查点中注明执行者。

每个 Agent 单独使用一个线程——先隔离，再整合：

memgit thread create agent-1     # branch off for each agent
# ... agents work on their own threads ...
memgit merge agent-1             # three-way merge back (common-ancestor based)

冲突（双方修改了同一条内存）会以最新版本为准；编辑始终优先于删除。两边的历史记录都会保留。

---

AI 能看到什么

通过 MCP 注册后，每个 AI 工具都会获得 6 个工具：

工具	AI 使用时机
resume_session	请求依赖先前状态时——例如“继续”“待处理的任务”，或会话开始时
search_memories	回答任何涉及过往工作或偏好的问题之前
get_memory	需要查看某条特定内存的完整详情时
list_memories	浏览或审查已存储的内容时
save_memory	学到值得留存以供下次使用的信息时
get_checkpoint_log	检查内存上次同步时间时

工具描述教会 AI 如何判断——“这个请求是否依赖上下文中没有的状态？”——而不是依赖关键词触发。整个工具集的实测成本：每个会话约 1,150 个 token；resume_session 的回复约为 335 个 token。

收到损坏内容时会拒绝保存，而不是存储（v0.13.0）。模型有时会用以字段命名的标签（</rule>）闭合某个值，随后主机便会将后续参数放入该值中：why、when、tags 和 type_code 都不会传入，内存则会使用默认值存储。在一台机器上，这种情况占了 3,025 次保存中的 748 次。现在，save_memory 会拒绝任何包含工具调用标记的值，指出受影响的字段和被吞入的参数，并让模型在同一轮中重试。故意在反引号中引用的标记不受限制。每次成功保存都会回显所存储的每个字段的长度、哪些字段为空，以及哪些值来自默认值。存储中已有的损坏内存绝不会再次提供到上下文中：摘要、召回钩子和读取结果都会显示每个字段在损坏处截断的内容。memgit doctor 会统计这些内存，而 memgit doctor --repair-markup 会将它们拆分回各自的字段。

---

核心运行指南（v0.5.0）

项目最难的上手问题不是它做什么，而是如何在其中开展工作：该调用哪个 skill、该运行哪个命令、该使用哪个工具。这些信息通常放在 CLAUDE.md 或 skills 文件夹中，而 AI 宿主未必配置为读取这些内容。memgit 会为你保管这些信息。

memgit core seed 会从项目现有的 skills 和规则文件中提炼出一份精简的运行指南。memgit core sync 会将其写入每个 AI 宿主各自的规则位置，作为专门由 memgit 管理的文件——.claude/rules/memgit.md、.cursor/rules/memgit.mdc、.windsurf/rules/memgit.md、.clinerules/、.roo/rules/、.continue/rules/——以及 GEMINI.md 中由标记界定的代码块（Gemini CLI 只会自动加载该文件）和 Codex 的 AGENTS.md。它只会增添内容——memgit 绝不会改动你自己的配置或内容——并会在会话开始时注入，因此即使项目缺少原生配置，任何工具也知道如何在项目中开展工作。

而且它还会不断学习：一个伴随使用情况的账本会追踪哪些记忆确实被调用过，使用最频繁的记忆会随着时间自动提升为指南中的指针（受预算限制、会随时间衰减，并且始终从属于仓库自身的规则——绝不会复述或覆盖这些规则）。如果内容已过时？memgit core heal 会重建它。

从 0.8.0 起，它还会自动启动：项目积累少量记忆后，系统会自动创建首份指南，因此整个流程不再依赖有人记得运行 core seed。指南开头会先说明项目实际包含的内容——“此项目保存了 N 条记忆，涉及主题”——因为明确列出真实历史工作的数量，是模型可以据此采取行动的证据；而抽象地指示模型检查记忆，则可能被模型拿来与自身信心比较，然后选择跳过。

---

memgit Pro——在所有机器上共享一份记忆

本地引擎、存储、MCP 服务和下方的所有命令均采用 MIT 许可，且永远不会受到限制。Pro 是面向使用多台机器或与团队协作用户的托管层：端到端加密同步，服务器只存储密文，通过一把许可证密钥解锁。

memgit pro activate <key>     # validate the key with Polar and store it (mode 0600)
memgit pro status             # Free / Pro, last verification, expiry
memgit pro deactivate         # remove the key from this machine

• 在 memgit.dev/#pricing 购买密钥——每月 $12 或每年 $99，由 Polar 结算（登记商户，负责处理税费）。密钥会通过电子邮件发送，也会显示在你的 Polar 购买页面中。
• 离开你机器的字节只有密钥和 memgit 的公开组织 ID，它们会发送到 Polar 的验证端点。记忆内容绝不会被发送。
• 无头宿主：在 MCP 服务的环境中设置 MEMGIT_LICENSE_KEY=<key>；系统会使用相同的缓存机制进行验证，且绝不会将密钥写入磁盘。
• 故障时默认放行：过去 14 天内验证通过的密钥在离线时仍可使用；密钥被拒绝时会降级为 Free，并显示明确消息。计划到期绝不会锁定你的数据——读取、拉取和导出仍可继续。
• 如果此存储已登录 memgit cloud，pro activate 也会升级该账户。

在机器之间以及与团队成员同步

memgit cloud signup --email [email protected]   # 14-day trial; keys are made on this machine
memgit cloud team create myteam
memgit cloud link myteam/memory               # creates the cloud repo on first link
memgit cloud auto on                          # every save syncs in the background from now on

启用自动同步后，每次保存（包括 AI 执行的每次 save_memory）都会启动一次后台拉取后推送，并立即返回；每次会话开始时，也会拉取其他机器保存的内容。memgit cloud auto status 会显示上次运行时间，以及未运行的原因。

在运行 Agent、但没有交互式会话的机器上（例如 Mac mini 或虚拟机），登录并关联一次，然后通过 systemd 或 launchd 保持内容为最新：

memgit cloud watch --interval 60                       # pull and push forever, one JSON line per run
memgit cloud watch --export ~/agent/.hermes.md         # also write the digest for agents that read context files

所有内容离开机器前都会进行端到端加密；服务器只存储密文。

---

真正会执行的备份

memgit 的理念是由 AI 执行操作，但过去备份需要人记得运行 memgit git init --remote <url> 并持续推送。以本项目自己的存储为例，这意味着 5 周下来，1,734 条记忆只存在一块磁盘上，没有任何副本。需要人手动执行命令的维护任务，最终都不会执行。

从 0.9.0 开始，它会在会话结束时自动运行，并将安全边界划在网络出口，而非操作成本上：

• 本地目标会自动备份——你已有的云同步文件夹（iCloud、Dropbox、Google Drive、OneDrive）或外接卷。memgit 只会复制文件；它不会建立连接，也不会注册任何服务。剩下的交给你现有的同步客户端处理。
• 只有在你已配置 Git 远程仓库时，才会推送到该仓库。 memgit 绝不会擅自添加远程仓库、创建仓库，也不会将记忆发送到你未选择的主机——记忆可能包含凭据，而便利并不足以成为理由，把它们发布到你从未选择的地方。

备份是单个 memgit-store.tar.gz，而不是目录树：一个 203 MB 的存储包含 10,295 个小型对象文件，每次都让同步客户端协调 10k 个文件，就会导致同步客户端永远无法完成。备份会先暂存，再以原子方式重命名；在新副本就位之前，旧副本会一直保留——备份中断绝不能让原本完好的文件被损坏文件取代。

memgit backup status     # where the last copy went, and what else is available

---

可验证的排序

过去，检索质量靠直觉调整。memgit eval 用测量取代直觉，采用从存储本身提取的两组固定数据集：

• recall——真实提示词，以及 memgit 实际为这些提示词检索出的记忆。衡量稳定性：改动是否破坏了原本有效的功能？
• synthetic——用每条记忆自身的 why 作为查询，预期结果为该记忆本身，并从查询中去掉 slug 自带的词语。独立于任何过往排序，衡量正确性。（单独使用 recall 集会形成循环论证——它的答案来自正在测试的排序。）

两组数据都会针对固定基线报告 hit@1、recall@3/5/10 和 MRR。这里刻意不提供单一综合分数，也不编造“节省的 token 数”。

这些评估很快就发挥了作用。为 0.8.0 实现的两项改动看起来显然正确，测量结果却证明并非如此：近期度乘数被撤下（真实提示词 hit@1 −0.020，MRR −0.018）；破坏性词干提取虽然修复了促使我们改动的查询，却让整体 hit@1 下降 −0.038（重建为增量字段后，结果分别提升 +0.020/+0.041/+0.019）。同一版本引入的 BM25 归一化错误也以同样的方式被发现。

---

深度宣传、跟踪器与替代关系（v0.6.0）

在 289 次真实会话中测得：注入的记忆触达了约 59% 的会话，但仅有 6.8% 的会话实际执行了主动搜索——注入的前 3 条记忆看起来像是“已查阅记忆”，因此模型始终不知道背后还有一个可查询的存储库。0.6.0 让被动层展示主动层掌握的信息：

• 记忆索引——恢复摘要以标签→计数对结尾（8a8f4ec (6) · instagram (5)），并附上深入查询的确切调用方式。计数真实准确：已被替代的记忆不会计入，且每个展示的主题都保证能返回搜索结果。
• “+N 条”记忆提示——如果每个提示词的记忆召回区块后面还有更多相关记忆，就会说明这一点，并告知获取这些记忆所需的一次调用。
• 上下文触发式记忆召回——一个 PostToolUse 钩子：读取路径与记忆标签匹配的文件时，会显示 memgit: 6 memories tagged 'x' relate to this path。仅读取提交时生成的标签映射缓存（绝不读取存储库），每个会话最多 3 次。
• 跟踪器（tr）——每个正在处理的实体对应一条记忆（<entity>-status），通过重新保存相同的 slug 来更新。它们会在每次会话顶部显示为状态看板：memgit 是实体状态的权威来源；文件内容可能滞后。
• 替代关系——更正内容会注明其替代对象（supersedes=[old-slug]），而不是使用“CORRECTED:”前缀。已被替代的记忆不会出现在搜索、记忆召回和恢复摘要中（保留历史记录；list 仍会显示这些记忆，并标记为 ⊘），因此注入的上下文永远不会过时。

---

命令

# Core (git-like)
memgit init                       # initialize store (auto-detects best path)
memgit onboard                    # bootstrap brief for an existing codebase
memgit add <slug> <rule>          # stage a memory (--body detail, --project scope, --global everywhere, --supersedes old-slug)
memgit commit -m "message"        # checkpoint current state
memgit log                        # history
memgit diff [sha1] [sha2]         # what changed
memgit show <slug>                # display a memory
memgit remove <slug>              # remove from active index (history preserved)
memgit status                     # staged changes
memgit search <query>             # BM25 search, scoped to this project + global (--all-projects to widen)
memgit rollback <ref>             # restore state to a checkpoint (HEAD~N or SHA)
memgit resume                     # where we left off — session-start digest
memgit merge <thread>             # three-way merge a thread into the current one
memgit remove <slug>              # (aliases: delete, rm, del) — mistypes get a "did you mean?"

# Core operating guide — per-project, always-on, cross-host
memgit core seed                  # draft a guide from this project's skills + rule files
memgit core sync                  # deliver it into each AI host's own rules file (additive)
memgit core show / edit           # view / curate the guide
memgit core heal                  # self-repair a guide that has drifted
                                  # (a project's FIRST guide is created automatically
                                  #  once it holds 5+ memories — no command needed)

# Durability — automatic, no human command required
memgit backup status              # last copy, staleness, available destinations
memgit backup now                 # force one immediately
memgit backup set <path>          # pin a destination
memgit backup off / on            # control the automatic path

# Retrieval evaluation — prove a ranking change helped
memgit eval mine                  # freeze a regression set from real recall events
memgit eval mine --synthetic      # non-circular set: query each memory by its own `why`
memgit eval run --set recall      # hit@1 / recall@3,5,10 / MRR vs the pinned baseline
memgit eval run --baseline        # pin the current result as the comparison point
memgit eval run --misses 10       # inspect the cases where nothing relevant surfaced

# Scale & proof
memgit squash                     # compress old history (archives what it collapses)
memgit gc                         # reclaim disk: sweep unreachable objects + stale session caches
memgit stats                      # measured context costs + disk usage
memgit doctor                     # hygiene + scope losses: split labels, quarantined, stale caches, orphaned usage
memgit doctor --audit             # every split and stranded label, the save landing rate, throughput
memgit doctor --audit --json      # the same report as JSON
memgit doctor --relabel map.json  # bulk re-project memories ({"slug": "Label" | ""}); one checkpoint
memgit doctor --repair-markup     # dry run: memories whose fields swallowed other parameters on save
memgit doctor --repair-markup --yes [--project LABEL]   # split them back into their fields; one checkpoint
memgit lint                       # validate all memories (flags unknown provenance)
memgit fsck                       # verify store integrity

# Import / export
memgit sync                       # sync from Claude Code files + commit (auto-finds them)
memgit import claude-code [path]  # path optional — defaults to ~/.claude/projects/*/memory
memgit import file <path>
memgit export <slug>

# Git sync (team features)
memgit git init [--remote URL]
memgit git push [remote] [branch]
memgit git pull [remote] [branch]
memgit git export
memgit git status

# AI tool registration
memgit setup                      # interactive step-by-step picker
memgit setup all                  # auto-register every detected tool
memgit setup claude-code
memgit setup cursor
memgit setup windsurf
memgit setup cline
memgit setup continue
memgit setup gemini-cli
memgit setup hooks                # Claude Code hooks: resume at start, per-prompt recall,
                                  # action gate on Bash and file writes, compliance and
                                  # capture guard + auto-sync at stop (--no-recall / --no-guard / --no-gate)
memgit doctor --rules             # critical rules next to same-topic lines in CLAUDE.md, AGENTS.md, ...

# Pro (licence key)
memgit pro activate <key>         # Polar-issued key; unlocks hosted E2E sync
memgit pro status / deactivate

# Server
memgit serve                      # MCP stdio (Claude Code, Cursor, Windsurf, Cline)
memgit serve --http               # HTTP REST (ChatGPT Custom Actions, Gemini)

# Visualization
memgit graph                      # D3.js interactive relationship map
memgit thread list / switch / create

---

AI 工具支持

工具	协议	命令
Claude Code	MCP stdio	memgit setup claude-code
Claude Desktop	MCP stdio	memgit setup claude-desktop
Cursor	MCP stdio	memgit setup cursor
Windsurf	MCP stdio	memgit setup windsurf
Cline / Roo-Code	MCP stdio	memgit setup cline
Continue.dev	MCP stdio	memgit setup continue
Codex	MCP stdio（TOML）	memgit setup codex
Antigravity	MCP stdio	memgit setup antigravity
Gemini CLI	MCP stdio	memgit setup gemini-cli
ChatGPT（自定义操作）	HTTP + OpenAPI	memgit serve --http → 导入 http://localhost:7474/openapi.json
Gemini API	HTTP 函数调用	memgit serve --http + llm-tool-definitions.json
任何 MCP 工具	MCP stdio	将 {"command": "memgit", "args": ["serve"]} 添加到配置中

---

memgit 会读取你环境中的哪些内容

memgit 在你的 Agent 中运行，因此，对于“这个进程会读取我环境中的哪些内容？”这个问题，诚实的答案应该可以核查，而不只是一个承诺。下表根据 memgit/env.py 生成，tests/test_env_inventory.py 会在每次测试运行时遍历软件包；如果代码读取了列表中未列出的名称，或列表包含了代码未读取的名称，测试就会失败。列表不会与代码脱节。

memgit 只读取以下内容，不读取其他内容，也不会写入其中任何内容。这些内容都不会开启网络访问：云端点只是你已通过 memgit cloud login 选择启用的同步功能的覆盖项；如果没有许可证，也没有登录云端，memgit 不会与任何对象通信。

	变量	memgit 对它的用途
存储与状态	MEMGIT_STORE	内存存储的绝对路径。设置后，它是唯一候选项——显式指定的存储绝不会静默回退到其他存储。
	MEMGIT_HOME	memgit 个人状态文件的基础目录，目前用于存放许可证文件（默认值为 ~/.memgit，模式为 0600）。
	MEMGIT_PROJECT	强制指定项目标签，而不是从工作目录中检测。
归属信息	MEMGIT_AUTHOR	检查点上标记的显式作者，适用于多个写入者共用同一机器账户的多 Agent 任务。优先级高于 MEMGIT_CLIENT。
	MEMGIT_CLIENT	启动此进程的主机（claude-code、cursor 等），会写入检查点，以便记录记忆的来源。
	USER	未设置 MEMGIT_AUTHOR 和 MEMGIT_CLIENT 时用作备用作者名称。
	USERNAME	Windows 上的 USER 备用值。
许可证（memgit Pro）	MEMGIT_LICENSE_KEY	memgit Pro 许可证密钥。绝不会完整显示——memgit pro status 会显示末尾四个字符。
	MEMGIT_POLAR_API	覆盖许可证验证 API 的基础 URL（用于测试）。
	MEMGIT_POLAR_ORG_ID	覆盖用于验证许可证的 Polar 组织。
云同步	MEMGIT_CLOUD_API	覆盖 memgit 云端 API 的基础 URL。
	MEMGIT_CLOUD_APP	覆盖 memgit 云端 Web 应用的基础 URL，用于生成显示的链接。
	MEMGIT_CLOUD_NO_CACHE	设置为 1/true/yes，可避免将解密后的密钥存入 credentials.json；此后每次运行命令都会重新提示输入密码短语。
	MEMGIT_NO_AUTOSYNC	设置为 1/true/yes，可仅对此进程禁用保存和会话启动时在后台与 memgit 云端同步。
调优	MEMGIT_LOCK_TIMEOUT	写入者等待存储锁后放弃的秒数（默认值为 10）。
	MEMGIT_IDLE_EVICT_SECONDS	MCP 服务在保持连接的同时，清除内存缓存前的空闲秒数（默认值为 900）。
	MEMGIT_HOUSEKEEPING_INTERVAL	MCP 服务两次执行清理任务之间的秒数。
由其他软件设置	CLAUDE_PROJECT_DIR	由 Claude Code 为钩子进程设置；当工作目录不是项目根目录时，作为项目检测的输入之一。
	PYTEST_CURRENT_TEST	由 pytest 设置。此变量存在时会禁用自动备份，因此测试运行绝不会写入真实的备份位置。

项目标签的判定方式

记忆按项目分类，因此标签错误会导致记忆被存放到你之后找不到的地方。标签取自以下第一个能得出标签的来源；MCP 服务、CLI 和钩子共用唯一一条检测路径，因此保存时和召回时得出的标签不会不一致：

1. MEMGIT_PROJECT — 强制指定的标签，原样使用
2. 主机在钩子负载中报告的 cwd（真实工作区，即使进程的工作目录在别处）
3. CLAUDE_PROJECT_DIR
4. 进程的工作目录

标签会保留 [A-Za-z0-9-]，并将所有其他字符转换为连字符，与 Claude Code 命名其 projects/ 目录的方式完全一致——包括 _ 字符，它会变成连字符。v0.12.0 之前写入的标签保留了 _；比较两个标签时，它们会折叠为连字符形式，因此旧形式下写入的内容仍可解析，已存储的内容也不会被改写。

项目的记忆如果分散在两个标签下，任何地方都不会报错：保存成功，fsck 也会保持干净，唯一的症状是回答会缺少内容。memgit doctor 默认会报告标签分散、孤立标签和保存命中率；memgit doctor --audit 会列出每一行。修复时会以目录存在的标签为准，不会以记忆数量更多的标签为准。

如果没有任何来源能得出标签——例如从 $HOME 运行——写入内容会被隔离到 _unknown 下，而不是全局存放；使用 memgit doctor --relabel 并指定其所属位置后，即可将其移至正确位置。将自由文本标签折叠到现有项目（log-report → Downloads-log-report），仅在输入是某个已知标签的尾部片段，且该标签已包含记忆时才会发生；任何存在歧义的情况都会保持原样，并且每次折叠都会报告，不会悄然执行。

---

TOON 格式——紧凑、易读、便于比较差异

标准 Markdown 记忆文件：

## Rule: Never mock the database in tests
**Type:** feedback  
**Priority:** medium  
**Why:** We got burned last quarter — mocked tests passed but the prod migration failed.  
**When to apply:** Any time writing tests that touch persistence layers.  
**Tags:** testing, database

同一条记忆的 TOON 格式：

TOON1|fb|no-db-mock|2026-07-01T10:00Z
#testing #database
PROJ:my-app
RULE:Never mock the database in tests
WHY:Mocked tests passed but prod migration failed last quarter
WHEN:Any persistence test
BODY:Full long-form detail lives here, losslessly (newlines escaped).\nSearch returns the compact RULE; get_memory returns everything.

使用真实分词器测量，TOON 比等效 Markdown 精简约 5–10%——这是不错的额外好处，但不是重点。重点在于检索节省：memgit 每次查询会加载相关度最高的 8 条记忆，而不是加载全部内容。

在 108 条记忆时：12,840 个 token（全部转储）→ 640 个 token（memgit BM25 top-8）

如需在 memgit stats 中获得精确的 token 数量，请安装可选分词器：pip install "memgit[tokens]"。

---

架构

~/.claude/memgit-store/
  .memgit/
    objects/     ← SHA-256 content-addressed blobs (gzip compressed)
    refs/threads/main   ← HEAD checkpoint SHA
    TOON_INDEX   ← active slug→sha mapping
    config       ← author, default thread
    logs/        ← ref change audit trail
  memories/      ← flat .toon files (git-trackable, human-readable)
  .git/          ← standard git repo (after `memgit git init`)

---

贡献

git clone https://github.com/code4161/memgit.git
cd memgit
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest    # 431 tests, all passing, < 5 seconds

参见 CONTRIBUTING.md。

---

路线图

• 内容寻址对象存储（与 git 完全相同的架构）
• TOON 格式（紧凑的逐行记忆格式）
• MCP 服务 — Claude Code、Cursor、Windsurf、Cline、Continue.dev
• HTTP 服务 — ChatGPT Custom Actions、Gemini function calling
• BM25 相关性搜索（只加载重要内容）
• memgit stats — 量化节省 token 的效果
• memgit squash — 扩展至 10k+ 个会话
• memgit git push/pull — 通过标准 git 进行团队同步
• 扁平的 memories/ 目录 — 对记忆执行 grep/diff/blame
• 使用 D3.js 可视化记忆关系图
• memgit resume + SessionStart hook — 会话从「上次进度」开始
• 防护钩子 — 每次提示词自动召回 + 会话结束时的捕获保护（v0.4.0）
• 核心操作指南 — 按项目配置、始终启用、跨主机、自我改进（v0.5.0）
• memgit gc — 回收空间（标记并清除、无损压缩归档）
• 多 Agent 写入安全 — 存储锁、自动合并提交、memgit merge
• 已发布至 PyPI + Homebrew（tap）+ npm（v0.1.5）
• Chocolatey — 已上线 community.chocolatey.org（choco install memgit）
• 交互式设置向导（memgit setup）
• 智能 memgit init（自动检测工具，无需指定路径）
• 无损记忆 — 除精简规则外，还保留完整的 body（v0.3.0）
• 项目范围的记忆 + memgit onboard 项目中期引导（v0.3.0）
• VS Code 扩展（v0.1.5，Marketplace：code416-memgit.memgit）
• 支持 Codex + Antigravity — MCP 注册 + AGENTS.md 核心指南（v0.8.0）
• memgit eval — 量化检索质量，采用真实且非循环的数据集（v0.8.0）
• 感知使用情况的排序 — 召回记录会影响相关性，而不仅仅是指南（v0.8.0）
• 自动初始化核心指南 — 自我改进循环自动启动（v0.8.0）
• 自动备份至其他设备 — 无需人工执行命令（v0.9.0）
• JetBrains 插件（第 3 阶段）
• 通过嵌入实现语义搜索 — 待 memgit eval 证明有实际提升后再启用（第 4 阶段）
• 公开基准测试数据（LongMemEval、LoCoMo）（第 4 阶段）
• memgit.dev 网站（已上线）
• 记忆压缩 / 自动摘要（第 5 阶段）
• 团队访问控制 + 审计记录（第 5 阶段）
• 记忆市场 — 分享可复用的上下文包（第 6 阶段）

---

许可证

MIT — 详见 LICENSE。