githippo

上下文压缩后，Claude 就会忘掉一切。
githippo 不会。

为 Claude 和任何 MCP 客户端提供长期记忆，以纯 Markdown 形式存储在由你拥有的 git 仓库中。它具备混合语义搜索、知识图谱、自动记忆和上下文压缩后续记能力，每轮工具调用开销约为 790 个 token。每条记忆都是一次 git 提交，你可以阅读、比较差异并还原。

curl -fsSL https://raw.githubusercontent.com/AnxovatomicaES/githippo/main/install.sh | sh

安装就这么简单：无需账户、令牌，也无需回答问题。它会设置本地记忆库，接入 Claude Code（钩子、MCP、状态栏），并在后台获取语义搜索。重启 Claude Code 后直接开始对话；它会记住。

想要备份并在多台设备间同步？githippo sync --github 会使用你现有的 GitHub CLI 登录创建一个私有仓库，并在每次更改后推送。只是想看看？npx -y github:AnxovatomicaES/githippo#v3.9.3 demo 会在 30 秒内展示运行效果，无需安装任何内容。

_{一键部署 → 在 claude.ai 和手机上使用}

为什么还要做另一个记忆服务？

因为现有的每个好点子都藏在不同的工具里。githippo 集各家所长，并解决最让人头疼的问题：

它还有哪些功能：

• 合规防护。 在内容进入永久 Git 历史记录之前，拦截私钥（包括 PGP）和 API 令牌（Anthropic、OpenAI、GitHub、AWS、Slack、Stripe、Google、SendGrid、npm、Hugging Face、JWT）、密码和机密赋值（password: …、DB_PASSWORD=…、AWS_SECRET_ACCESS_KEY=…）、嵌入密码的连接字符串、银行卡安全码、IBAN（经过 mod-97 校验，可带空格或连字符）、银行卡号（经过 Luhn 校验，即使旁边还有其他数字也能识别）、西班牙 DNI/NIE、法国 NIR（校验和）、英国国民保险号码（以大写字母书写）和美国 SSN。它能识别伪装成相似字母的字符、其他文字系统中的数字和零宽字符；而「password: required」「tokens: 128000」之类的普通文本，或「12/10/26」这样的西班牙日期，则不会被拦截。它还会捕获不透明的 Authorization: Bearer/Basic 标头、GitLab、Google OAuth、Slack 和 Discord 的 webhook 与机器人令牌、Telegram、Twilio、Mailgun、Azure、Shopify、PyPI 和 DigitalOcean 令牌、STRIPE_KEY= 这类环境变量行、PIN，以及密码以带引号的 JSON、Markdown 粗体和「the password is …」形式出现的情况。但经过 Base64 编码、拆分到多个单词中或经过 URL 编码的机密仍可能漏过：这只是后备防护，并非 DLP。
• 从设计上防止压缩导致信息丢失，共有三种方式（见下文）。
• 跨语言回忆。 默认的多语言嵌入模型在本地运行；用西班牙语提问，也能找到用英语写的笔记。
• 更新绝不会被误认为重复项。 「在第一季度末发布」和「在第二季度末发布」的嵌入向量几乎相同。githippo 还会比较数字、日期和名称，因此更新会被保存，旧行会被标记，maintain 会报告可能存在的矛盾。相关测量见 docs/calibration.md。如果每条事实都包含另一条所没有的实词（「dark」/「light」、「weekly」/「monthly」、「read」/「write」），它们也绝不会被判为重复项，因为关键词重合和嵌入都无法区分同义词与反义词：新事实会被保存并标记为可能的更新，而 maintain 会将这两条列为可能存在矛盾。（实施此规则前，在关键词模式下，此类 12 对事实中有一半会被静默丢弃。）
• 乐观并发控制。 两个会话同时编辑同一份记忆时，不会互相覆盖；冲突失败的一方会收到当前文件并进行合并。

在三层深度压缩后依然留存

Claude Code 压缩冗长会话时，对话会被总结，细节也会消失。githippo 确保重要内容不会丢失。

flowchart LR
  A[Context fills up] --> B[PreCompact hook]
  B -->|parse transcript, no LLM| C[checkpoint: goal, todos, files, where it stopped]
  C --> D[(local ~/.githippo)]
  C --> E[(repo sessions/)]
  F[Compaction] --> G[SessionStart hook, source=compact]
  D --> G
  G -->|injects the state itself, not a reminder to read it| H[Claude continues exactly where it stopped]
  I[MCP instructions + core memory] -.->|system prompt, never compacted| H

1. 系统提示词中的核心记忆。 MCP 服务指令不属于对话，因此压缩不会影响它们。你固定的重要信息始终保留，适用于任何 MCP 客户端。
2. 由钩子驱动的检查点（Claude Code）。常见的抱怨是：压缩后钩子如果只是提醒 Claude 重新读取状态文件，效果时好时坏。githippo 会直接注入内容。检查点上限约为 900 个 token；当会话内容超出上限时，它会优先舍弃价值最低的细节（较早的摘要、命令、较早的请求、已完成的任务），绝不会丢掉目标、未完成的任务或停下的位置。
3. checkpoint 工具（任何客户端，包括 claude.ai）。Claude 会在关键节点保存任务、状态和下一步。上下文丢失后，不带参数调用 checkpoint 即可恢复。

额外功能：同一项目和分支中的新会话，如果距离上次会话不超过 24h，会收到一条简短提示，说明“你上次在做什么……”，并包含 Git 的变更情况（提交、其他人的提交、分支切换、已删除的文件）。UserPromptSubmit 钩子会在匹配置信度较高时主动展示最多三条相关记忆。其上限为 300 个 token，会跳过简单提示，并且在同一会话中不会重复展示。提示词中知识库从未见过的词会降低匹配度，因此，普通编码提示即使与某条记录共享两个常见词（如“重构”“使用”），也不会触发记忆注入：在 1,000 到 10,000 条记录的测试中，20 条无关编码提示均未触发注入，而 40 个预设问题全部触发了正确记录（test/report6-hook.test.js）。压缩前，githippo 还会告知压缩器哪些内容必须保留；压缩后，它会将压缩器的摘要与检查点一并保存。

我们如何确认这些钩子的行为与描述一致：相关契约取自 Claude Code 自身的代码（2.1.258）。PreCompact 会将每个成功钩子的标准输出作为自定义指令传给压缩器（Claude Code 也会在记录中将这段文本显示为“PreCompact … completed successfully”）；PostCompact 会接收 compact_summary；每个钩子都会接收 session_id、transcript_path 和 cwd；SessionStart 的来源包括 startup、resume、clear、compact 和 fork。

Recall 还会逐渐了解你实际使用的内容：反复提供给 Claude 的记忆会获得小幅加权（关键词分数最多提高 +40%，语义分数最多提高 +10%），每连续 30 天未使用就衰减一半。加权会应用于原始分数，因此只会调整排名相近的结果：不会让明显匹配项失去第一名（早期版本在排名融合后应用加权，确实导致过这种情况，见 test/report6-ranking.test.js）。使用计数保留在你的机器上，并按用户分别记录；如果没有使用数据，排名结果与未启用加权时完全相同。

将内容放在 <private>…</private> 中，它就永远不会进入记忆。如果开标签没有闭合，之后的所有内容都会被视为私密内容；remember 会拒绝保存这条信息并说明原因，而不会悄悄保存你原本打算隐藏的部分。无需编辑文件即可关闭钩子：GITHIPPO_HOOK_PROFILE=minimal 或 GITHIPPO_DISABLED_HOOKS=prompt,steer。

质量：已测量的部分（以及尚未测量的部分）

在一个小型标注集（52 个查询）和 LongMemEval-S（500 个问题，仅检索，不使用 LLM）上进行检索测试：

运行 githippo eval 可复现第一项结果。方法、按语言划分的结果、归档和重复项准确率、内存用量及规模数据，请参阅 docs/benchmarks.md。该测试集规模较小，由作者手工编写，且属于特定领域：它是回归检查和粗略参考，并非排行榜。

**尚未测量，但这是最重要的指标：**与不使用 githippo 相比，使用它是否能改善回答，或降低会话成本。eval/qa.js 和 eval/behavior.js 专为测量这一点而构建，需要 ANTHROPIC_API_KEY；目前还没有运行。在测量之前，请这样理解“节省 token”：它会给每轮对话带来有限的成本（见下文），只有在回忆起的事实能替代重新解释或重新发现信息时，才能抵消这笔成本。如果你运行了这些测试，请将结果发布到 issue #3。

你该使用 githippo 吗？

• Claude 内置记忆是无需设置的选择。如果你希望记忆以文件形式保存，方便阅读、比较差异、在 Obsidian 中编辑并自行备份；希望 Claude Code、Claude Desktop、claude.ai 和其他 MCP 客户端共享同一份记忆；或希望记忆在 Claude Code 压缩上下文后仍然保留，请使用 githippo。
• basic-memory 是最接近的替代方案：同样使用 Markdown，兼容 Obsidian，项目更成熟，采用 Python，许可证为 AGPL。githippo 的不同之处在于 Git 历史和时间回溯、上下文压缩钩子、带文件夹权限的 OAuth 团队保险库，以及机密信息防护。
• mem0 和其他托管服务会使用 LLM 提取事实并将其存储在云端，无需你运行任何程序。githippo 保存事实时从不调用 LLM，并会将所有内容保存在你拥有的仓库中。
• 它还很新。 githippo 是一个由单人维护的项目（首次提交于 2026 年 10 月），陌生用户尚未在大规模场景下使用过它。这里提供了基准测试、200 多项测试、每晚运行的带种子模糊测试器、五轮审计问题记录（test/report*.test.js：每项问题都先复现，再通过回归测试修复）和发行说明，供你评估；但请做好遇到不完善之处的准备。

Claude 原生功能（选择启用，已测量）

最后三项每次运行都会消耗 API 额度，因此它们需要选择启用，结果目前也尚未列入此 README。

令牌预算（使用 githippo bench 测得）

实现方式：精简架构，从 tools/list 中移除冗余的 $schema URL，以紧凑的文本响应替代格式化 JSON，将维基链接呈现为普通文字，移除 frontmatter，使用 8 字符版本句柄，默认不在召回时包含 History/index/sessions/core，并为每个摘要包设置令牌预算。

每轮最坏情况下的代价：工具架构约 790 + 指令约 200 + 核心记忆最多 400（CORE_BUDGET_TOKENS），总计约 1,400 个令牌；如果每提示词钩子找到高置信度匹配，则相关提示词还会额外增加最多 300 个令牌；此外还有 recall 返回的内容（mode=brief 约 47 个令牌，默认情况下摘要包最多 1,000 个令牌）。架构、指令和核心记忆构成稳定前缀，因此使用提示词缓存的客户端实际消耗会低于原始计数。githippo 并不会因为存在本身就节省令牌：只有当召回的事实替代了重复解释或重新发现信息时，才会节省令牌。

时间开销方面：钩子会在每次提示前运行，状态行也会持续运行，因此启动开销尽量保持精简（它们不会加载任何服务端代码）。在开发机器上，githippo bench 报告钩子耗时约 57 毫秒，状态行耗时约 60 毫秒，而单独运行 node 耗时 39 毫秒；在服务端导入改为惰性加载之前，耗时为 125 毫秒。运行 githippo bench 查看你自己的数据。

工具

设置

平台：Linux 和 macOS 会在每次变更时通过 CI 测试；暂不支持 Windows（失败情况及原因见 docs/platforms.md），WSL 的行为应与 Linux 一致。

Claude Code（完整体验：钩子 + MCP）

curl -fsSL https://raw.githubusercontent.com/AnxovatomicaES/githippo/main/install.sh | sh

想看看实际运行的内容？这是一个简短的 shell 脚本：检查 Node 20+，运行 npm i -g github:AnxovatomicaES/githippo#v3.9.3，然后运行 githippo setup。setup 可重复执行，不会影响已有的状态行，并会在修改 ~/.claude/settings.json 前备份该文件。之后，githippo doctor 会检查所有项目（如果某项检查失败，则以非零状态码退出）。githippo uninstall 会移除钩子、状态行和 MCP 条目，但保留你的记忆；githippo <command> --help 会说明任意命令的用法，输入错误的选项时会给出建议，而不会执行命令。

从官方参考记忆服务迁移？运行 githippo import ~/path/to/memory.jsonl，即可将其中的实体、观察和关系转换为笔记和类型化链接（会应用密钥防护和去重，因此可以安全地重复运行）。 插件方式：运行上面的安装命令（用于 githippo 命令），然后执行 /plugin marketplace add AnxovatomicaES/githippo 和 /plugin install githippo。该插件提供钩子和 MCP 服务，而 githippo setup / githippo install 会检测到它，不会重复安装（以前这会导致每个钩子运行两次）。如果两者都已安装，请运行 githippo uninstall，并保留插件。或者，将 INSTALL_FOR_AGENTS.md 交给你的 Agent。

githippo sync --github            # creates a private repo "githippo-memory" with your gh login

githippo users add john --acl "shared/:write,people/:read"   # prints his password once
githippo users list

纯 Markdown，兼容 Obsidian。将仓库作为知识库打开，即可直接使用图谱视图。

---
name: billing-v2
title: Billing v2
type: project
description: Billing rewrite
aliases: [billing rewrite]
---

## Decisions
- Use idempotency keys on every write endpoint
- owner:: [[sam-okafor]]
- Launch target is end of Q1

## History
- ~~Launch target is end of Q4~~ (until 2026-09-30)

目录结构：core.md（固定）、index.md（目录）、inbox.md（未分类的事实）、people/、projects/、topics/、decisions/、sessions/（检查点）。参见 examples/memory。

笔记名称可以包含空格、重音符号和任何文字体系（my notes.md、café.md、笔记.md），因此从 Obsidian 同步的知识库可以直接使用。只有在任何地方都不安全的名称会被拒绝（控制字符、\ < > : " | ? *、隐藏名称）。Frontmatter 会被视为不可信内容：异常值（title: []、超大字段、__proto__）无法破坏搜索；若某篇笔记无法读取，系统会跳过它并发出警告，而不会导致记忆功能崩溃。包含未解决 git 冲突标记的笔记绝不会被索引或写入；合并或变基尚未完成时，githippo 会拒绝写入。

配置

所有配置都遵循同一规则：先读取环境变量，再读取 ~/.githippo/config.json，最后使用默认值。大多数人会设置的选项包括：VAULT_DIR（默认 ~/.githippo/vault）、EMBEDDINGS（local、static、voyage 或 none）、GITHIPPO_CONFIRM（auto、strict 或 off），以及 PROMPT_RECALL=0（关闭每个提示词的钩子）。其他所有配置，包括远程服务和团队知识库相关变量，都列在 docs/configuration.md。

坦诚说明安全模型

• 你的文件，你的数据。 githippo 没有后端。记忆保存在你机器上的一个文件夹中；备份会推送到你拥有的私有仓库。githippo 会匿名询问 GitHub，确认备份远程仓库是否可公开读取：如果可以，githippo doctor 会失败，githippo sync 不会向其推送，后台推送也会拒绝（可通过 GITHIPPO_ALLOW_PUBLIC_BACKUP=1 主动覆盖）。它只能检查 GitHub 远程仓库；如果使用其他托管平台，请自行检查仓库的可见性。
• **本地使用时不存储令牌。**同步使用 git 已有的登录方式（GitHub CLI、SSH 或密钥链）。只有远程服务需要令牌：请创建一个细粒度令牌，仅限一个仓库，并且只授予 Contents 读取/写入权限。
• 远程身份验证采用 OAuth 2.1（仅支持 PKCE S256、动态客户端注册、一次性授权码，以及绑定到 /mcp 资源和用户当前密码及 ACL 的令牌）。刷新令牌会轮换：每个令牌只能使用一次；如果再次提交已使用过的令牌（这表明令牌可能已被复制），该次登录的所有令牌都会被撤销，包括访问令牌；重复使用授权码也会产生同样结果。签名采用无状态方式（HMAC），因此重启不会让任何人退出登录。旧版 URL 中的密钥方式（/mcp/<secret>）默认关闭，因为 URL 会出现在代理日志中；只有设置 LEGACY_SECRET_URL=1 才会启用。服务器会以 400 错误响应格式错误的请求，而不会崩溃；会验证每个请求正文、限制重复登录失败的频率、限制并统计每次调用中的 JSON-RPC 批量请求数量，并按套接字地址限流。
• **防护措施只是最后一道防线，并非 DLP。**它能识别常见的密钥和 ID 格式。forget 会从当前文件中删除一行，但 git 历史中仍会保留；要彻底清除，必须重写历史记录。
• **文件夹权限能抵御各种绕过手段。**团队知识库路径只会规范化一次，权限检查与存储使用同一路径，因此空格、不可见字符、.. 以及（在大小写不敏感的磁盘上）大小写变更都无法绕过规则，其中也包括 macOS 和 Windows 对 ſ、ß 和 fi 的折叠方式。index.md 只会向每位读者显示其有权读取的笔记；如果两个可读笔记声明了同一个名称，系统会将事实发送到你的收件箱，而不会自行猜测。其他用户的 users/<id>/ 文件夹不会受通配规则影响。
• **核心记忆是最受信任的文本，因此只有一个写入入口。**通过工具写入核心记忆只能使用 pin（如果你的客户端支持，会先向你确认；来自外部来源的事实则会被拒绝），不能使用 remember about:"core" 或 files 工具；来自外部来源的内容绝不会加载到核心记忆中，且其令牌预算会严格限制可加载的内容。
• **远程会话无法请求确认。**确认功能使用 MCP elicitation，而无状态 HTTP 请求没有用于确认的通道，因此远程服务上的 GITHIPPO_CONFIRM=auto 不会发起确认。如果你希望拒绝未经确认、来自外部来源的事实、写入核心记忆的固定内容和移除操作，请在远程服务上设置 GITHIPPO_CONFIRM=strict。
• **任何人都可以用任意名称注册 OAuth 应用。**动态客户端注册是开放的（claude.ai 正是通过这种方式连接），因此登录页面会显示浏览器接下来将跳转到哪里，并提示只有在连接由你发起时才继续。
• **外部文本始终只是数据。**网页、文件或工具输出中的事实会标记为 [external]，在移动、改写和整合过程中都会保留该标记。看起来像是向 AI 发出指令的文本会被拒绝（适用于所有写入途径：remember、files 工具、记忆工具和大模型改写；检查时既会检查原文，也会检查回忆时显示的内容，因此注释、链接别名或不可见字符都无法将其隐藏）。这种检查针对常见措辞，属于启发式机制，并非万无一失：改写后的文本可能会通过检查，因此核心记忆有独立的写入入口，外部事实也会被标记。检查点会中和这类文本，且无法伪造章节内容。
• **尊重 Git 状态。**githippo 不会干扰你发起的合并或变基，不会提交冲突标记，并会将 bisect、分离的 HEAD 或关联工作树视为“忙碌”状态并明确提示。
• **钩子不会中断会话，也不需要在 PATH 中找到 githippo。**所有失败路径都会在短超时后以 0 退出。在 macOS 和 Linux 上，setup 会将 node 和 githippo 的绝对路径写入钩子、状态行和 MCP 条目，因此当 Claude Desktop 或 IDE 启动 Claude Code 时，即使其 PATH 比你的 shell 短，这些配置仍能正常工作；如果 node 的路径发生变化，钩子会先尝试从 PATH 查找 node，再查找 githippo；如果两者都无法运行（例如 githippo 已卸载），钩子就不会执行任何操作。移动或重新安装后再次运行 githippo setup，会更新已有配置；githippo doctor 会提示固定路径是否已失效。（Claude Code 插件的钩子仍会通过 PATH 查找 githippo。）
• 已知限制。.mcpb 包尚未进行代码签名；删除的事实会继续保留在 git 历史中，直到你重写历史记录；对回答质量的提升效果尚未测量（见上文）。

开发

npm ci && npm test      # 200+ tests: unit, hooks, adopted features, bug regressions, local vault, setup, end-to-end over Streamable HTTP with the official MCP client
npm run fuzz            # seeded fuzzing of every entry point (FUZZ_SEED=<n> FUZZ_ITERATIONS=<k> to reproduce or go deeper); runs nightly in CI with a fresh seed
npm run bench           # token cost of the tool surface
node scripts/versions.mjs   # every version string and pinned tag agrees (CI and the release check this)

路线图

签名的 .mcpb 发布版本 · SSO（GitHub/Google）作为团队保险库的 OAuth 身份提供商 · 为远超 50,000 条笔记的保险库提供可选的派生 SQLite 索引 · Claude Code 默认支持 MCP Apps（聊天内存浏览器）后再推出 · 如果 Claude 的客户端有朝一日声明支持 MCP sampling，则支持 MCP sampling（Claude Code 2.1.302 只声明支持 roots 和 elicitation，因此整合与上下文检索仍需要 ANTHROPIC_API_KEY）

采用 MIT 许可证。欢迎提交 PR。