hmem — Humanlike Memory for AI Agents

hmem — 面向 AI Agent 的类人记忆

你的 AI 会忘掉会话之间的一切。hmem 可以解决这个问题。

只需调用一次 load_project()。约 3000 个 token。你的 Agent 就能了解项目中所有重要信息——过去的每个错误、每项决策、每个待办任务——跨会话、跨设备、跨 AI 提供商。无需为每次对话单独设置。也不用“让我重新阅读代码库”。它就是会记住。

AI Agent？ 跳过此文件。请阅读 AGENT_SETUP.md——这份文档是为你而非人类编写的。

命名说明（v8.0）： 这个软件包曾短暂以 its-over-9k（1.x）的名称发布。现在它又叫 hmem——纯粹的记忆框架，不包含其他内容。its-over-9k 这个名称现在属于一个独立项目：o9k token-efficiency meta-framework，它会组合此类技能和插件。相关项目：TIM——hmem 的下一代继任者（超图记忆、CRDT 同步）。

这是什么

hmem 不是笔记插件，而是面向 AI Agent 的记忆框架——一套完整的基础设施层，用于持久、可移植且节省 token 的知识，让知识能够跨越会话边界、设备切换和提供商变更。

四大核心保障：

问题所在

每个 AI 会话都从零开始。你的 Agent 会问相同的问题、犯相同的错误、与上周的决策自相矛盾，还会浪费 50k 个 token 加载昨天已经处理过的上下文。

你试过各种变通办法——CLAUDE.md 文件、自定义提示词、手动粘贴上下文。但这些办法无法扩展。你有 10 个项目，在 3 台设备之间切换，还会使用不同的 AI 工具。

解决方案

You:    "Load project"
Agent:  [calls load_project("P0048") — 3000 tokens]
Agent:  "v1.2.9, TypeScript/SQLite/npm. 3 open bugs, 8 roadmap items.
         Last session: rebrand complete, rename_id bug fixed (89 changes).
         Next: O-Entry Auto-Purge. What's the focus today?"

就这么简单。只需 3000 个 token，就能获得完整的项目简报。Agent 会了解技术栈、架构、未解决的 Bug、近期决策，以及你上次停下的位置——即使昨天的“你”是在另一台机器上使用另一个 AI 的你。

工作原理

Level 1  ──  One-line summary          (always loaded — ~5k tokens for 300+ entries)
  Level 2  ──  Paragraph detail        (loaded on demand)
     Level 3  ──  Full context          (loaded on demand)
      Level 4  ──  Extended detail      (loaded on demand)
        Level 5  ──  Raw/verbatim data  (loaded on demand)

会话开始时，Agent 会加载第 1 级摘要——每条记忆占一行。需要细节时，它会逐层深入。300 条记忆只需 5k 个 token 即可浏览概览。单个项目约需 3000 个 token。

不会丢弃任何摘要内容。 第 1 级是压缩视图，但第 2 至第 5 级保留了完整的原始文本，逐字不差，并可按需访问。

框架功能

自动会话记忆

每次对话都会自动记录。不需要“保存你的工作”之类的提示，也不需要手动创建检查点。

You type  →  Agent responds  →  Stop hook fires  →  Exchange saved to O-entry
                                                   →  Linked to active project
                                                   →  Haiku auto-titles the session

在会话中途切换项目？O 条目也会随之切换。在另一台设备上开始新会话？下一个 Agent 会看到所有设备上的每次交流——对话永远不会消失。

Haiku 后台检查点

每经过 N 次交流（可配置，默认值为 5），一个 Haiku 子 Agent 就会在后台启动。它会阅读近期对话，提取经验教训、遇到的错误和作出的决策，然后将这些内容写入长期记忆——并拥有完整的 MCP 工具访问权限。主 Agent 不会受到任何打扰。

检查点还会在项目中写入一条交接说明：“已完成以下工作，以下工作正在进行，下一步是……”。下一个 Agent 无论使用哪台设备、哪个提供商，都能从你上次停下的位置准确接续。

基于项目，而非基于会话

会话无关紧要。项目才是一切。

• O-条目关联到当前活动项目，而非会话
• 检查点计数器统计项目交互次数，而非会话消息数
• load_project 会显示近期对话及其完整上下文，涵盖所有设备

技能系统

hmem 附带完整的技能层——结构化行为文件，Agent 可按需加载。技能定义 Agent 应如何执行某项操作（调试、编写记忆、整理条目、处理会话开始），与记忆和提示词相互独立。

npx hmem update-skills    # Pull latest skills to your AI tool's skill directory

技能会独立进行版本管理和更新。无需重新安装，Agent 就能变得更智能。默认附带 21 项技能：

公司记忆

除了个人记忆，Agent 还可以维护一个共享的公司存储库——独立的 company.hmem，供多个 Agent 和团队成员读取。个人记忆和公司记忆可以共存；Agent 会同时查询二者。

import { openCompanyMemory } from 'hmem';
const store = openCompanyMemory('/path/to/project');

可嵌入的 SDK

hmem 附带完整文档的 TypeScript SDK——可将 HmemStore 直接导入你自己的 Agent、工具或自动化流水线：

import {
  HmemStore, openCompanyMemory, resolveHmemPath,
  loadHmemConfig, saveHmemConfig, DEFAULT_CONFIG, DEFAULT_PREFIXES, formatPrefixList,
  searchMemory,
} from 'hmem';
import type {
  AgentRole, MemoryEntry, MemoryNode, HmemConfig,
  SearchResult, SearchOptions, SearchScope,
} from 'hmem';

const store = new HmemStore('/path/to/agent.hmem');
const results = searchMemory('/path/to/project', 'auth token bug', { maxResults: 5 });

MCP 工具

hmem 附带两个 MCP 服务：

• hmem（日常使用，13 个工具）——读取、写入、搜索和项目生命周期管理。
• hmem-curate（维护，11 个工具）——批量编辑、架构迁移、备份和恢复。仅在整理时启用。

hmem — 日常使用的服务（13）

hmem-curate — 维护服务（11）

日常使用的 hmem 服务由 hmem init 自动注册。hmem-curate 默认不启用，因为其中的工具具有破坏性——需要整理时再注册：

npx hmem mcp-add-curate          # adds the curate server to Claude Code (user scope)

然后仅在整理会话期间通过 /mcp 启用它。其他 MCP 客户端请参阅手动设置。

CLI 命令

执行 npm install -g hmem-mcp 后，hmem 二进制文件会加入 PATH。

面向用户

钩子驱动程序（由 AI 工具调用，不要手动调用）

整理

同步（需要安装 hmem-sync）

备份 / 迁移

hmem serve 会直接启动 MCP stdio 服务——你的 AI 工具会自动启动它；你只需在调试时手动运行。

记忆类别

默认前缀（可通过 hmem.config.json 中的 prefixes 配置）：

在 hmem.config.json 的 prefixes 下列出自定义前缀（例如，A 表示应用，F 表示函数参考），即可添加这些前缀——它们会自动出现在 read_memory({ prefix: "X" }) 筛选条件中。

快速开始

1. 安装

npm install -g hmem-mcp

2. 运行交互式安装程序

npx hmem init

它会检测你的 AI 工具、创建记忆目录、配置 MCP，并安装所有钩子：

3. 验证

重启 AI 工具，然后：

read_memory()

空响应 = 正常工作（首次运行）。错误 = 检查故障排除部分。

手动设置

{
  "mcpServers": {
    "hmem": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/hmem/dist/mcp-server.js"],
      "env": {
        "HMEM_PROJECT_DIR": "/home/yourname/.hmem",
        "HMEM_AGENT_ID": "DEVELOPER"
      }
    }
  }
}

echo "Node: $(which node)"
echo "Server: $(npm root -g)/hmem/dist/mcp-server.js"

{
  "mcp": {
    "hmem": {
      "type": "local",
      "command": ["/absolute/path/to/node", "/absolute/path/to/hmem/dist/mcp-server.js"],
      "environment": { "HMEM_PROJECT_DIR": "/home/yourname/.hmem" },
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "hmem": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/hmem/dist/mcp-server.js"],
      "env": { "HMEM_PROJECT_DIR": "/home/yourname/.hmem" }
    }
  }
}

配置

HMEM_PROJECT_DIR 中的 hmem.config.json（或 Agents/NAME/ 中）：

{
  "memory": {
    "maxCharsPerLevel": [200, 2500, 10000, 25000, 50000],
    "maxDepth": 5,
    "checkpointMode": "auto",
    "checkpointInterval": 5,
    "recentOEntries": 10,
    "maxTitleChars": 50,
    "prefixes": { "X": "Custom" }
  },
  "sync": {
    "serverUrl": "https://your-server/hmem-sync",
    "userId": "yourname",
    "salt": "...",
    "token": "..."
  }
}

所有键都是可选的。缺少的键将使用默认值。

各运行环境的检查点设置

自动检查点 Agent 会在每 N 次交互后于后台运行。它需要调用大模型，有三种自动选择的方式：

1. 环境变量中有 API 密钥（任何运行环境）→ 直接调用服务提供商 API。请在 hmem.config.json 中配置 checkpointProvider、checkpointModel 和 checkpointApiKeyEnv。适用于 Pi、Hermes、OpenCode 和 Claude Code。
2. 没有 API 密钥，但 PATH 中有 claude CLI → 使用子进程回退方案（claude -p）。Claude Code / Claude Max 用户无需配置。
3. 两者都没有 → 检查点会失败，并提示配置错误。

推荐的低成本设置（DeepSeek，约比 Haiku 便宜 10 倍）：

{
  "memory": {
    "checkpointMode": "auto",
    "checkpointProvider": "openai",
    "checkpointModel": "deepseek-chat",
    "checkpointBaseUrl": "https://api.deepseek.com/v1",
    "checkpointApiKeyEnv": "DEEPSEEK_API_KEY"
  }
}

然后在你的 shell 配置文件中执行 export DEEPSEEK_API_KEY=sk-...。适用于任何运行环境。

Claude Code / Claude Max（无需配置）： 无需设置服务提供商选项——子进程回退方案会使用你现有的 claude 登录信息。

各运行环境的交互日志记录： Claude Code 使用 Stop hooks（由 npx hmem init 安装）。Pi 使用内置扩展（src/extensions/pi-hmem.ts）。Hermes 需要 hermes-hmem 插件（参见 plugins/hermes-hmem/README.md）。OpenCode 使用与 Claude Code 相同的 hook 系统。

⚠ Pi 用户： 基于 Hook 的交互日志记录目前在 Pi 运行时中无法正常工作。交互不会自动保存到 O 条目。在此问题解决之前，可通过 hmem checkpoint 手动创建检查点。

跨设备同步

使用零知识 AES-256-GCM 加密，在所有设备间同步记忆。

npm install -g hmem-sync
npx hmem-sync connect     # Interactive wizard — first device creates, others join

将 HMEM_SYNC_PASSPHRASE 添加到 MCP 配置中，即可在每次读写时自动同步。

多服务冗余

{
  "sync": [
    { "name": "primary", "serverUrl": "https://server1/hmem-sync", "userId": "me", "salt": "...", "token": "..." },
    { "name": "backup",  "serverUrl": "https://server2/hmem-sync", "userId": "me", "salt": "...", "token": "..." }
  ]
}

公告

向所有设备上已同步的 Agent 广播：

npx hmem-sync announce --message "Server URL changing — update your config!"

Windows

在安装了 Git for Windows 的 Windows 系统上，Claude Code 默认会通过 Git Bash 执行 hook 和 statusLine 命令。Git Bash 的 MSYS2 运行时在启动时会间歇性崩溃，导致命令尚未运行就被终止。

修复方法：在 ~/.claude/settings.json 的每个 hook 命令和 statusLine 中添加 "shell": "powershell"。

完整可用配置请参见 settings.windows.example.json。主要区别如下：

{
  "env": {
    "HMEM_PATH": "C:/Users/YOUR_USERNAME/.hmem/Agents/DEVELOPER/DEVELOPER.hmem"
  },
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "node C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/hmem/dist/cli.js log-exchange",
        "shell": "powershell"
      }]
    }]
  },
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/hmem/dist/cli.js statusline",
    "shell": "powershell"
  }
}

运行 npm root -g，获取适用于你机器的正确 node_modules 路径。

Windows 上的 statusLine： 设置 "shell": "powershell" 后即可稳定运行。不设置时，statusLine 会间歇性消失。

故障排查

更新

npm update -g hmem    # MCP server + SDK
npm update -g hmem-sync      # Sync (if installed)
npx hmem update-skills       # Refresh skill files

License

MIT