Hippo：生物启发的 Agent 内存架构

好记忆的秘诀不在于记得更多。而在于懂得遗忘什么。

AI 智能体的记忆层。以海马体为原型。默认衰减，使用强化，每条记忆都有出处标记。SQLite 作为底层，零运行时依赖，兼容你拥有的每一个 CLI 智能体。

npm install -g hippo-memory && hippo init --scan ~

一条命令。你机器上的每个 git 仓库都会获得记忆能力。

兼容:        Claude Code、Codex、Cursor、OpenClaw、OpenCode、Pi、任何 MCP 客户端
导入来源:     ChatGPT、Claude（CLAUDE.md）、Cursor（.cursorrules）、Slack、markdown
存储:        SQLite 骨干网 + markdown 镜像副本。可 Git 跟踪，人类可读。
依赖:        零运行时依赖。Node.js 22.5+。可选嵌入：自带本地 Transformers.js（`npm i @huggingface/transformers`，或传统的 `@xenova/transformers`）或可选 API 嵌入器（OpenAI/Voyage/Cohere）。不会自动安装任何东西。

大多数"AI 记忆"系统保存所有数据，稍后再搜索。那只是附加了语义搜索的存储而已。这就是为什么你的智能体上周在同一个部署 bug 上卡了一次，前一周又卡了一次。系统看到过四次失败。它没有办法判断自己应该记住这个。

Hippo 应用了大脑在过去 5 亿年来一直做对的事情。记忆随时间衰减。检索使它们变强。三个生物学层（缓冲层、情景层、语义层）在休息期间聚合。困难的教训之所以牢固，因为你使用过它们。琐碎的细节之所以淡去，因为你没有。

它也解决了可迁移性问题。你的 ChatGPT 记忆无法转移到 Claude。你的 .cursorrules 无法转移到 Codex。Hippo 是每个智能体背后的一个进程。CLAUDE.md、Cursor 规则、ChatGPT 导出、Slack 历史，全部在一个 SQLite 存储里，可从任何支持 MCP 或 HTTP 的工具查询。

用数字说话，不用形容词。每一项声明都关联到证明它的基准测试或测试。

顺序学习基准。benchmarks/sequential-learning/。50 个任务，10 个隐藏陷阱。衡量智能体是否从过去的错误中学习，而不仅仅是检索文本。v0.11.0 非正式幅度 RETRACTED v1.7.9；机制保持交付。见 CHANGELOG.md v1.7.9 条目。

R@5 = 74.0% 在 LongMemEval 上。500 题工业检索基准，仅 BM25，无嵌入。

10/10 事故场景 在暂存 Slack 语料库上战胜了逐字稿回放（benchmarks/e1.3/）。回忆比滚动最后 N 条消息更快地浮现根因。

1000 事件摄入烟雾测试中零出站 HTTP。由一个在调用时抛出异常的 globalThis.fetch 侦探验证，不是硬编码的零。

926 个测试，真实数据库，零 mock。项目规则。早期咬我们一次的 mock-vs-prod 分歧现在是让后续十个版本保持诚实的约束。

dlPFC 目标条件聚类判别，3/3 查询通过 —— 完整目标堆栈，带策略加权和生命周期窗口化的结果传播。在 BM25 单独无法判别的 3 聚类夹具上的按目标提升；确定性测试见 benchmarks/micro/results/b3-depth.json。

它为你的智能体做什么

停止重复犯错。用 --tag error 标记一次失败，每次智能体走回代码的那个部分时，这个教训都会浮现。错误衰减得比普通观察慢。

跨工具存活。周一用 Claude Code，周二用 Cursor，周三用 Codex。同一个 .hippo/ 存储。同样的记忆。精确地从中断处继续。

摄入记录系统。今天 Slack（POST /v1/connectors/slack/events）。GitHub、Jira、Notion 紧随其后。Webhooks 落地为 kind='raw' 记忆，完整出处和 GDPR 正确删除。

知道每条记忆从何而来。每一行都携带 kind、scope、owner 和 artifact_ref。被遗忘的权利是一个 API 调用，不是审计噩梦。

和多租户相处融洽。API 密钥 scrypt 哈希。每次变动都有审计日志。租户 A 根本看不到租户 B 的记忆。由负测试证明。

npm install -g hippo-memory

# 单个项目
hippo init

# 你的所有项目一次（推荐）
hippo init --scan ~

--scan 找到你主目录下每个 git 仓库，在每一个里创建 .hippo/ 存储，并用最后 30 天提交历史的教训来播种。一条命令，跨所有项目即时获得记忆。

设置后，hippo sleep 在会话结束时运行（通过自动安装的智能体钩子），并做五件事：

从今天的 git 提交学习

从 Claude Code MEMORY.md 文件导入新条目

聚合记忆（衰减、合并、清理）

去重几乎相同的记忆，保留更强的副本

将高价值教训分享到全局存储，以便在每个项目中浮现

# 手动使用
hippo remember "FRED cache silently dropped the tips_10y series" --tag error
hippo recall "data pipeline issues" --budget 2000

完整发布历史：CHANGELOG.md · GitHub Releases

零配置 Agent 集成

hippo init 自动检测你的 Agent 框架并将自己接入：

cd my-project
hippo init

# Initialized Hippo at /my-project
#    Directories: buffer/ episodic/ semantic/ conflicts/
#    Auto-installed claude-code hook in CLAUDE.md

如果你有 CLAUDE.md，它会修补它。Codex/OpenClaw/OpenCode 用 AGENTS.md。Cursor 用 .cursorrules。你的 Agent 在下一个会话开始时就开始使用 Hippo。对于 Codex 会话捕获，Hippo 只在你明确选择用 hippo hook install codex 时才包装 codex 启动器（init 在检测到 Codex 时会打印命令；随时用 hippo hook uninstall codex 撤销）。

它也在 Hippo 的工作区注册表中注册当前项目，并安装一个机器级日常运行器（6:15am）。那个运行器扫过每个注册的工作区，运行 hippo learn --git --days 1，然后 hippo sleep。你得到严格的日常聚合，而无需为每个项目创建一个操作系统任务。

跳过：hippo init --no-hooks --no-schedule

你的记忆不应该被锁在一个工具内。Hippo 从任何地方拉进来。

# ChatGPT 记忆导出
hippo import --chatgpt memories.json

# Claude 的 CLAUDE.md（跳过现有的 hippo 钩子块）
hippo import --claude CLAUDE.md

# Cursor 规则
hippo import --cursor .cursorrules

# 任何 markdown 文件（标题变成标签）
hippo import --markdown MEMORY.md

# 任何文本文件
hippo import --file notes.txt

所有导入命令支持 --dry-run（预览不写入）、--global（写入 ~/.hippo/）和 --tag（添加额外标签）。重复项会自动检测并跳过。

从原始对话文本中提取记忆。不需要 LLM：基于模式的启发法找到决策、规则、错误和偏好。

# 管道一个对话
cat session.log | hippo capture --stdin

# 或指向一个文件
hippo capture --file conversation.md

# 先预览
hippo capture --file conversation.md --dry-run

Slack 摄入（E1.3）

Hippo 在 POST /v1/connectors/slack/events 上接受 Slack Events API webhooks。配置 SLACK_SIGNING_SECRET（在每个请求上验证）并指向 Slack 到 https://<your-host>/v1/connectors/slack/events。消息落地为 kind='raw' 记忆，带 slack://team/channel/ts 出处和 slack:public:Cxxx 或 slack:private:Cxxx 作用域。源删除被遵守（GDPR）。

回填现有频道：SLACK_BOT_TOKEN=xoxb-... hippo slack backfill --channel C0000。检查格式错误的事件：hippo slack dlq list。

多工作区部署填充 slack_workspaces（team_id、tenant_id）以按租户路由事件；单工作区回退到 HIPPO_TENANT。

活动任务快照

长期运行的工作需要短期连续性，不仅仅是长期记忆。Hippo 可以持久化当前飞行中的任务，以便稍后的继续有具体的东西来恢复。

hippo snapshot save \
  --task "Ship SQLite backbone" \
  --summary "Tests/build/smoke are green, next slice is active-session recovery" \
  --next-step "Implement active snapshot retrieval in context output"

hippo snapshot show
hippo context --auto --budget 1500
hippo snapshot clear

hippo context --auto 在长期记忆之前包括活动任务快照，所以智能体既得到即时线程又得到更深层的教训。

手动快照很有用，但真实工作也需要面包屑踪迹。Hippo 现在可以存储短会话事件并将它们链接到活动快照，以便上下文输出显示最新步骤，而不仅仅是最后的摘要。

hippo session log \
  --id sess_20260326 \
  --task "Ship continuity" \
  --type progress \
  --content "Schema migration is done, next step is CLI wiring"

hippo snapshot save \
  --task "Ship continuity" \
  --summary "Structured session events are flowing" \
  --next-step "Surface them in framework hooks" \
  --session sess_20260326

hippo session show --id sess_20260326
hippo context --auto --budget 1500

Hippo 将最新踪迹镜像到 .hippo/buffer/recent-session.md，这样你可以在不打开 SQLite 的情况下检查短期线程。

当你今天完成（或切换到另一个 Agent）时，创建一个交接，以便下一个会话知道精确地从哪里开始：

hippo handoff create \
  --summary "Finished schema migration, tests green" \
  --next "Wire handoff injection into context output" \
  --session sess_20260403 \
  --artifact src/db.ts

hippo handoff latest              # show the most recent handoff
hippo handoff show 3              # show a specific handoff by ID
hippo session resume              # re-inject latest handoff as context

工作记忆是用来记录当前状态笔记的有界暂存区。它与长期记忆相互独立，并会在会话之间被清空。

hippo wm push --scope repo \
  --content "Investigating flaky test in store.test.ts, line 42" \
  --importance 0.9

hippo wm read --scope repo        # show current working notes
hippo wm clear --scope repo       # wipe the scratchpad
hippo wm flush --scope repo       # flush on session end

每个作用域的缓冲区最多容纳 20 个条目。缓冲区已满时，重要性最低的条目会被淘汰。

查看某条记忆为何会被返回：

hippo recall "data pipeline" --why --limit 5

# --- mem_a1b2c3 [episodic] [observed] [local] score=0.847
#     BM25: matched [data, pipeline]; cosine: 0.82
#     ...memory content...

输入首先进入缓冲区。重要内容会被编码到情景记忆中。在“睡眠”期间，重复出现的情景会被压缩成语义模式。微弱的记忆则会衰减并消失。

flowchart TD
    I[New information] --> B[Buffer<br/>session-only, no decay]
    B -->|encode: tags, strength, half-life| E[Episodic Store<br/>timestamped, decay by default<br/>retrieval strengthens, errors stick]
    E -->|hippo sleep<br/>replay + merge| S[Semantic Store<br/>compressed patterns, stable<br/>schema-aware]
    E -.->|decay| X[forgotten]
    S -.->|recall| E
    classDef bio fill:#fff4dc,stroke:#a8742d,color:#2b1b00
    classDef forgotten fill:#f5f5f5,stroke:#999,color:#666,stroke-dasharray:5 5
    class B,E,S bio
    class X forgotten

在逐一介绍各项功能之前，先来看一条记忆在典型会话中的生命周期：

sequenceDiagram
    autonumber
    actor Agent
    participant B as Buffer
    participant E as Episodic
    participant S as Semantic
    Agent->>B: hippo remember "cache dropped tips_10y" --error
    B->>E: encode (half_life=14d, valence=neg)
    Note over E: strength=1.0
    Agent->>E: hippo recall "data pipeline"
    E-->>Agent: returns memory (rank 1)
    Note over E: half_life 14d → 16d, retrieval_count++
    Agent->>E: hippo outcome --good
    Note over E: reward_factor 1.0 → 1.15
    Agent->>S: hippo sleep
    S->>E: merge 3 related episodic → 1 semantic
    Note over E,S: original episodic decays, pattern survives

每条记忆都有半衰期，默认为 7 天。持久留存需要靠自身价值赢得。

hippo remember "always check cache contents after refresh"
# stored with half_life: 7d, strength: 1.0

# 14 days later with no retrieval:
hippo inspect mem_a1b2c3
# strength: 0.25  (decayed by 2 half-lives)
# at risk of removal on next sleep

检索会强化记忆

用进废退。每次召回都会使半衰期增加 2 天。

hippo recall "cache issues"
# finds mem_a1b2c3, retrieval_count: 1 -> 2
# half_life extended: 7d -> 9d
# strength recalculated from retrieval timestamp

hippo recall "cache issues"   # again next week
# retrieval_count: 2 -> 3
# half_life: 9d -> 11d
# this memory is learning to survive

当你从一个工具迁移到另一个工具时，有关已被替换工具的旧记忆应当立即消亡。执行 hippo learn --git 时，Hippo 会检测迁移及破坏性变更提交，并主动削弱匹配的记忆。

hippo learn --git
# feat: migrate from webpack to vite
#    Invalidated 3 memories referencing "webpack"
#    Learned: migrate from webpack to vite

你也可以手动使记忆失效：

hippo invalidate "REST API" --reason "migrated to GraphQL"
# Invalidated 5 memories referencing "REST API".

架构决策

一次性决策不会重复出现，因此无法仅凭检索来赢得留存资格。hippo decide 会以 90 天的半衰期和已验证的置信度存储这些决策，使其能够存续足够长的时间，真正发挥作用。

hippo decide "Use PostgreSQL for all new services" --context "JSONB support"
# Decision recorded: mem_a1b2c3

# Later, when the decision changes:
hippo decide "Use CockroachDB for global services" \
  --context "Need multi-region" \
  --supersedes mem_a1b2c3
# Superseded mem_a1b2c3 (half-life halved, marked stale)
# Decision recorded: mem_d4e5f6

将一条记忆标记为错误，它的半衰期就会自动变为原来的 2 倍。

hippo remember "deployment failed: forgot to run migrations" --error
# half_life: 14d instead of 7d
# emotional_valence: negative
# strength formula applies 2.0x multiplier (HIPPO_LOSS_AVERSION_RATIO=0.75 to keep v1.13.4 1.5x)

# production incidents don't fade quietly

每条记忆都有一个置信度级别：verified、observed、inferred 或 stale。这能让 AI 智能体知道，它们应该在多大程度上信任正在读取的内容。

hippo remember "API rate limit is 100/min" --verified
hippo remember "deploy usually takes ~3 min" --observed
hippo remember "the flaky test might be a race condition" --inferred

生成上下文时，置信度会显示在行内：

[verified] API rate limit is 100/min per the docs
[observed] Deploy usually takes ~3 min
[inferred] The flaky test might be a race condition

AI 智能体一眼就能区分哪些是已确定的事实，哪些只是值得质疑的模式。

超过 30 天未被检索的记忆，会在下一次执行 hippo sleep 时自动标记为 stale。如果它之后再次被召回，Hippo 会将其唤醒并恢复为 observed，使其能够重新赢得信任，而不是永久停留在陈旧状态。

Hippo 会检测内容有重叠的记忆之间存在的明显矛盾，并让这些矛盾保持可见，而不是悄无声息地让双方都冒充事实。仅仅共享标签并不算矛盾；陈述本身必须在内容上存在重叠。

hippo sleep       # refreshes open conflicts
hippo conflicts   # inspect them

未解决的冲突会存储在 SQLite 中，同时镜像到 .hippo/conflicts/ 下，并通过每条记忆的 conflicts_with 字段反向关联。

记忆不会以毫无背景的断言形式呈现。默认情况下，Hippo 会将其表述为带日期的观察记录，让 AI 智能体把它们视为上下文，而不是命令。

hippo context --framing observe   # default
# Output: "Previously observed (2026-03-10): deploy takes ~3 min"

hippo context --framing suggest
# Output: "Consider: deploy takes ~3 min"

hippo context --framing assert
# Output: "Deploy takes ~3 min"

共有三种模式：observe（默认）、suggest 和 assert。你可以根据希望记忆具有多强的指令性进行选择。

运行 hippo sleep，情景就会被压缩成模式。

hippo sleep

# Running consolidation...
#
# Results:
#    Active memories:    23
#    Removed (decayed):   4
#    Merged episodic:     6
#    New semantic:        2

三个或更多相互关联的情景会被合并为一条语义记忆。原始情景逐渐衰减，模式则得以留存。

召回的记忆真的有帮助吗？把结果告诉 Hippo，它会借此收紧反馈闭环。

hippo recall "why is the gold model broken"
# ... you read the memories and fix the bug ...

hippo outcome --good
# Applied positive outcome to 3 memories
# reward factor increases, decay slows

hippo outcome --bad
# Applied negative outcome to 3 memories
# reward factor decreases, decay accelerates

结果会累积计算。一条拥有 5 次正面结果、0 次负面结果的记忆，其奖励因子约为 1.42，使有效半衰期延长 42%。一条拥有 0 次正面结果、3 次负面结果的记忆，其奖励因子约为 0.63，衰减速度接近原来的两倍。正负结果混合时，奖励因子会趋近中性值 1.0。

只召回容得下的内容，不要向上下文中硬塞信息。

# fits within Claude's 2K token window for task context
hippo recall "deployment checklist" --budget 2000

# need more for a big task
hippo recall "full project history" --budget 8000

# machine-readable for programmatic use
hippo recall "api errors" --budget 1000 --json

结果按相关性 × 强度 × 时效性排序。信号最强的记忆会优先填充预算。

Hippo 可以扫描你的提交历史，并自动从 fix、revert 和 bug 提交中提取经验。

# Learn from the last 7 days of commits
hippo learn --git

# Learn from the last 30 days
hippo learn --git --days 30

# Scan multiple repos in one pass
hippo learn --git --repos "~/project-a,~/project-b,~/project-c"

--repos 标志接受以逗号分隔的路径。Hippo 会扫描每个仓库的 Git 日志，提取 fix、revert 和 bug 经验，与已有记忆进行去重，并存储新记忆。之后配合运行 hippo sleep 进行整合。

非常适合设置为每周执行的 cron 任务：

hippo learn --git --repos "~/repo1,~/repo2" --days 7
hippo sleep

使用 hippo watch 包装任意命令，即可自动从失败中学习：

hippo watch "npm run build"
# if it fails, Hippo captures the error automatically
# next time an agent asks about build issues, the memory is there

框架集成

自动安装（推荐）

hippo init 会检测你的 AI 智能体框架，并自动修改正确的配置文件：

无需其他命令。只需运行 hippo init，你的 AI 智能体就会知道 Hippo。

如果你更喜欢显式控制：

hippo hook install claude-code   # 修改 CLAUDE.md，并添加 SessionStart/SessionEnd + UserPromptSubmit 钩子
hippo hook install codex         # 可选的修复/手动运行：修改 AGENTS.md，并包装检测到的 Codex 启动器
hippo hook install cursor        # 修改 .cursorrules
hippo hook install openclaw      # 修改 AGENTS.md
hippo hook install opencode      # 修改 AGENTS.md，并安装 opencode TS 插件

这会添加一个 <!-- hippo:start --> ... <!-- hippo:end --> 块，指示 AI 智能体：

在会话开始时运行 hippo context --auto --budget 1500

出现错误时运行 hippo remember "<lesson>" --error

完成任务时运行 hippo outcome --good

对于 Claude Code，它还会添加：

一个 SessionEnd 钩子，以便会话退出时自动运行 hippo sleep

一个 SessionStart 钩子，用于输出上一次会话的整合结果

一个 UserPromptSubmit 钩子，在每轮交互时运行 hippo context --pinned-only --include-recent 5 --format additional-context。它会重新注入置顶记忆（hippo remember <text> --pin）以及最近 5 次写入，因此同一会话中新产生的经验会在下一条提示词之前出现，供你决定是否将其置顶。若要关闭此功能，请在 .hippo/config.json 中设置 {"pinnedInject":{"enabled":false}}。

移除方式：hippo hook uninstall claude-code

钩子添加的内容（以 Claude Code 为例）

## Project Memory (Hippo)

Before starting work, load relevant context:
hippo context --auto --budget 1500

When you hit an error or discover a gotcha:
hippo remember "<what went wrong and why>" --error

After completing work successfully:
hippo outcome --good

对于任何兼容 MCP 的客户端（Cursor、Windsurf、Cline、Claude Desktop）：

hippo mcp   # starts MCP server over stdio

将以下内容添加到你的 MCP 配置中（例如 .cursor/mcp.json 或 claude_desktop_config.json）：

{
  "mcpServers": {
    "hippo-memory": {
      "command": "hippo",
      "args": ["mcp"]
    }
  }
}

提供以下工具：hippo_recall、hippo_remember、hippo_outcome、hippo_context、hippo_status、hippo_learn、hippo_wm_push。

原生插件，支持自动注入上下文、基于工作区的记忆查找，以及用于自动学习/自动休眠的工具钩子。启用 autoSleep 后，OpenClaw 插件现在会在会话结束时，通过一个分离的后台工作进程启动 hippo sleep，从而让当前会话立即退出。

查询时的检索仍会同时使用当前工作区存储和共享的全局存储。每日整合则由 hippo init / hippo setup 安装的机器级运行程序完成。

openclaw plugins install hippo-memory
openclaw plugins enable hippo-memory

插件文档：extensions/openclaw-plugin/。集成指南：integrations/openclaw.md。

带有 SessionStart/Stop 钩子和错误自动捕获功能的插件。参见 extensions/claude-code-plugin/。

完整的集成详情：integrations/

Hippo 以人类海马体的七种特性为模型。这不是比喻，而是字面意义上的模拟。

为什么需要两个存储区？大脑使用快速的海马体缓冲区和缓慢的新皮层存储区（互补学习系统理论，McClelland 等，1995）。如果新皮层学习得太快，新信息就会覆盖旧知识。缓冲区吸收新的经历，而新皮层则随着时间推移提取其中的模式。

为什么衰减会有帮助？齿状回中新生的神经元会主动扰乱旧的记忆痕迹（Frankland 等，2013）。这是一种适应性机制：它能减少过时信息造成的干扰。遗忘不是失败，而是维护。

为什么错误会留下深刻印象？杏仁核会根据情绪意义调节海马体的记忆整合。恐惧和错误信号会增强编码。你第一次遇到的生产事故会深深烙印在记忆中，而第 200 次平安无事的部署则不会。

为什么检索会强化记忆？被回忆起来的记忆会经历“再巩固”（Nader 等，2000）。检索行为会使记忆痕迹变得不稳定，随后再以更强的形式重新编码。这就是测试效应。Hippo 通过在回忆时延长半衰期，以机械方式实现这一机制。

为什么睡眠会整合记忆？睡眠期间，海马体会重放近期经历的压缩版本，并通过反复激活相同模式来“教导”新皮层。Hippo 的 sleep 命令将这一过程作为一次有意执行的整合阶段来运行。

全部 7 种机制：PLAN.md#core-principles

有关这些机制如何与 LLM 训练、持续学习和开放研究问题相联系的说明：RESEARCH.md

为什么奖励会调节衰减？在脉冲神经网络中，奖励调制的 STDP 会强化那些促成积极结果的突触，并削弱未能促成积极结果的突触。Hippo 的奖励比例衰减机制（v0.11.0）实现了这一点：持续产生积极结果的记忆衰减得更慢，产生消极结果的记忆衰减得更快，而且不使用固定的增减量。其灵感来自 MH-FLOCKE 用于四足运动的 R-STDP 架构；在该架构中，相同机制实现了稳定学习，方差比 PPO 低 11.6 倍。

AI 智能体记忆模拟领域的先行研究。类似人类的记忆会让类似人类的行为作为涌现属性出现，这一理念已在 2010—2011 年的 IEEE 研究（5952114、5548405、5953964）中得到探索。在房间之间走动，却忘了自己为什么过去，并不需要直接模拟；这种行为会自然地从具有容量限制和衰减机制的记忆系统中涌现。Hippo 的设计遵循相同原则：实现这些机制，行为自然会随之出现。

相关工作：HippoRAG（Gutierrez 等，2024）通过知识图谱将海马体索引应用于 RAG。MemPalace（Sigman 与 Jovovich，2026）使用 AAAK 压缩，以空间方式组织记忆（侧翼/大厅/房间），在 LongMemEval 上达到 100%。MH-FLOCKE（Hesse，2026）使用带有 R-STDP 的脉冲神经元实现具身认知。每个系统都解决了不同方面的问题：HippoRAG 优化检索质量，MemPalace 优化检索组织方式，MH-FLOCKE 优化具身学习，而 Hippo 优化记忆生命周期。

AI 记忆这一类别在 2026 年迅速走向成熟。Hippo 的独特方案——生物衰减