hmem (Bumblebiber)

its-over-90k-人工智能记忆框架

你的AI在会话之间会忘记一切。 其超过9k的修复 --还有更多。

一 load_project() 电话。约3000个代币。你的代理人知道一个项目的所有重要信息——过去的每一个错误、每一个决定、每一项未完成的任务-- 跨会话、设备和AI提供商。 每个对话都没有设置。不是“让我重新阅读代码库”。它只是 *记得*.

AI代理？ 跳过此文件。阅读 AGENT_SETUP.md --为你而写，不是为人类而写。

______________________________________________________________________

这是什么

its-over-9k不是一个记笔记的插件。这是一个 内存框架 AI代理——一个完整的基础设施层，用于持久、可移植、令牌高效的知识，在会话边界、设备切换和提供者更改中幸存下来。

四大核心保障：

______________________________________________________________________

问题

每个AI会话都从零开始。你的代理会问同样的问题，犯同样的错误，与上周的决定相矛盾，并浪费5万个令牌加载昨天已经处理过的上下文。

您已经尝试了变通方法——CLAUDE.md文件、自定义提示、手动粘贴上下文。它们不会缩放。你有10个项目。您可以在3台设备之间切换。你使用不同的AI工具。

解决方案

You:    "Load project"
Agent:  [calls load_project("P0048") — 3000 tokens]
Agent:  "v7.4.1, 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个代币用于完整的项目简报。代理知道堆栈、架构、打开的错误、最近的决定，以及你离开的确切位置——即使“你”昨天是不同机器上的不同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)

在会话开始时，代理加载级别1摘要——每个内存一行。当它需要细节时，它会深入挖掘。您的300个条目内存需要花费5000个令牌才能浏览。单个项目的成本约为3000个代币。

没有什么是概括的。 级别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入口也会切换。在其他设备上启动新会话？下一个代理看到每个设备上的每个交换-- 谈话永远不会结束.

Haiku背景检查点

每N次交换（可配置，默认5次），Haiku子代理就会在后台唤醒。它读取最近的对话，提取经验教训、遇到的错误和做出的决定，然后将它们写入长期记忆中——具有完整的MCP工具访问权限。你的主要代理人永远不会被打扰。

检查点还写入 交接单 对于项目：“这是已经完成的工作，这是正在进行的工作，下面是下一步。”下一个代理——在任何设备上，任何提供商上——都会从你停止的地方继续。

基于项目，而非基于会话

会议毫无意义。项目就是一切。

• O-条目链接到活动项目，而不是会话
• 检查点计数器统计项目交换，而不是会话消息
• load_project 显示最近在所有设备上的完整上下文对话

技能体系

它拥有9000多艘船只 技能层 --代理按需加载的结构化行为文件。技能定义 *怎么* 代理应该做一些事情（调试、写入内存、管理条目、处理会话启动）——与内存和提示分开。

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

技能是独立版本和更新的。您的代理无需重新安装即可变得更聪明。

公司记忆

除了个人记忆，代理人还可以保持 共享公司商店 --一个单独的 company.hmem 多个代理和团队成员可以从中读取。个人记忆和公司记忆并存；代理同时查询两者。

import { openCompanyMemory } from 'its-over-9k';
const store = openCompanyMemory('/path/to/project');

可嵌入SDK

它的9000多个版本作为一个完整记录的TypeScript SDK发布——导入 HmemStore 直接进入您自己的代理、工具或自动化管道：

import { HmemStore, openCompanyMemory, searchMemory, loadHmemConfig } from 'its-over-9k';

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

______________________________________________________________________

MCP工具（12）

______________________________________________________________________

内存类别

通过自定义前缀 hmem.config.json.

______________________________________________________________________

快速开始

1.安装

npm install -g its-over-9k

2.运行交互式安装程序

npx hmem init

检测您的AI工具，创建内存目录，配置MCP，并安装所有钩子：

3.验证

重新启动AI工具，然后：

read_memory()

空响应=工作（第一次运行）。错误=检查 故障排除部分.

手动设置

Claude Code — edit ~/.claude/.mcp.json

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

查找路径：

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

Open Code — edit ~/.config/opencode/opencode.json

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

Cursor / Windsurf / Cline

编辑 ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json，或 .vscode/mcp.json:

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

______________________________________________________________________

配置

hmem.config.json 在你的 HMEM_PROJECT_DIR （或 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": "..."
  }
}

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

每个线束的检查点设置

自动检查点代理在每N次交换后在后台运行。它需要一个LLM调用——三条自动选择的路径：

1. API密钥在环境中 （任何安全带）→ 直接提供程序API循环。配置 checkpointProvider + checkpointModel + checkpointApiKeyEnv 在 hmem.config.json。来自Pi、Hermes、OpenCode和Claude Code的作品。
2. 没有API密钥，但是 claude PATH中的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"
  }
}

然后 export DEEPSEEK_API_KEY=sk-... 在您的shell配置文件中。适用于任何线束。

克劳德代码/Claude Max（零配置）： 不需要提供程序设置——子流程回退使用您现有的 claude 登录。

每次线束交换记录： 克劳德代码使用 Stop 挂钩（由安装 npx hmem init).Pi使用内置扩展(src/extensions/pi-hmem.ts).赫尔墨斯需要 hermes-hmem 插件（参见 plugins/hermes-hmem/README.md).OpenCode使用与Claude Code相同的钩子系统。

______________________________________________________________________

跨设备同步

使用零知识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": "..." }
  ]
}

公告

向所有设备上的所有同步代理广播：

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

______________________________________________________________________

视窗

在Windows和Git for Windows上，默认情况下，Claude Code通过Git Bash路由钩子和statusLine命令。Git Bash的MSYS2运行时在启动时短暂崩溃，在命令运行前将其终止。

修复：添加 "shell": "powershell" 执行每一个钩子命令 statusLine 在 ~/.claude/settings.json.

看 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/its-over-9k/dist/cli.js log-exchange",
        "shell": "powershell"
      }]
    }]
  },
  "statusLine": {
    "type": "command",
    "command": "node C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/its-over-9k/dist/cli.js statusline",
    "shell": "powershell"
  }
}

跑 npm root -g 为了得到正确的答案 node_modules 您的机器的路径。

Windows上的状态行： 稳定与 "shell": "powershell"没有它，雕像线会间歇性地消失。

______________________________________________________________________

故障排除

______________________________________________________________________

更新

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

______________________________________________________________________

许可证

麻省理工学院