Skip to main content
Glama

hy-mem

本地长期记忆服务,为 AI Agent 提供跨会话的记忆存储与语义检索能力。基于 Tencent Hy-Memory SDK 2.0.15 构建,内置多厂商模型预设(OpenAI 兼容 / 智谱 / 百炼 / DeepSeek,含自定义网关)。

A local long-term memory CLI for AI agents — write, fact-extract via LLM, semantic search, and tag archiving, with a built-in MCP stdio server (9 tools).

下载安装

平台

下载

Windows x64

hy-mem-win64.zip(免 Python,解压即用;zip 恒名不带版本号,解压覆盖即升级)

其他版本与历史发布见 Releases。

安装三步:解压到任意目录 → 双击「安装到 PATH.cmd」(或直接运行 hy-mem.exe)→ 首次运行进设置向导,配好向量模型与密钥即可使用。

Related MCP server: mcp-memory

功能特性

  • MCP 服务:内置 stdio MCP server(9 工具:add/search/get/update/delete/list + queue_status + get_version + evolve_status),任何支持 MCP 的客户端(WorkBuddy / Claude Desktop / Cursor 等)即插即用。pro 模式下 evolve_status 不出现在 tools/list 里,客户端拿不到也就调不动

  • L6 认知层(仅 ultra):行为模式归纳全自动——add 素材攒够(默认 ≥8 条新事实)且距上次尝试 ≥24h 就后台自动跑,无需手动触发;evolve_status 工具或 CLI hy-mem evolve-status(所有模式可看)查进度与历史,get_version 在连续失败时会顺带带出 evolve_health 异常信号。归纳模型与抽取/判重分开配(config set evolve.model=…)——抽取(llm.model)配分析类小模型(如 tongyi-xiaomi-analysis-flash,封闭判定够用且快),归纳(evolve.model)配更强的通用大模型(如 deepseek-v4.1-flash):弱模型能抽取但做不了开放归纳。手动逃生门:CLI hy-mem evolve(直连模式下可用)

  • ⚠️ ultra 单写者语义:L6 图库用 kuzu(独占锁,无 read_only),同一数据目录图库只允许一个进程持有。本版本起内置上游补丁:持锁冲突时自动降级为图 no-op(事实/向量/检索完全正常,仅该进程写入的记忆暂缺 L4 关系边,可用 graph-build 批量回填),不再抛错死信。servePort 可为 serve 固定端口(默认 0=随机);serve 重启换端口后,MCP 长驻 client 会自动检测并重建端点(U3 自愈),无需重启客户端

  • 语义检索:基于向量相似度的记忆搜索,写入时 LLM 自动抽取事实与标签

  • 异步写入:非阻塞式入队,自动拉起后台 worker 消费;队列状态全程可查(pending / dead / shadow)

  • 标签管理:灵活的标签系统,支持归档与分类

  • 交互式配置:设置菜单 + 首次安装向导,连通性实测通过才放行

  • 多身份支持:通过 user_id 区分不同 Agent 的记忆空间

快速开始

安装依赖

pip install -r requirements.txt

初始化配置

首次运行需执行设置向导:

python -m hymem setup

或启动交互式菜单:

python -m hymem menu

基本命令

命令

说明

add

添加记忆(支持单条/多条/带标签)

search

语义检索记忆(支持 queries 多路并行检索)

list / get / update / delete

列出 / 详情 / 修改 / 逻辑删除

forget / finalize

彻底删除 / 清理逻辑删除残留(--language 指定归纳语言)

tags / untag / archive

标签与归档管理

stats / doctor

统计 / 19 项健康自检

queue / worker / drain / retry

异步队列查看 / 消费 / 清空 / 重投(含 shadow 影子重投)

backup / restore

数据面快照备份 / 恢复

vdb-scan / vdb-plan / vdb-reembed / vdb-reembed-graph / vdb-drop

向量空间巡检 / 重嵌计划 / 执行重嵌 / 图重嵌 / 删除空间(换嵌入模型后迁移用)

graph-build

存量记忆批量回填 L4 关系图(图库重建/降级补边用)

profile

用户画像查看(--full 含全部演化细节)

mcp / serve

启动 MCP stdio 服务 / HTTP 服务

setup / config / user / install

设置菜单 / 配置管理 / 身份切换 / 注册到 PATH

history / log / skill / migrate / version

操作历史 / 运行日志 / Skill 安装 / 数据迁移 / 版本

evolve

手动归纳 L6 行为模式(逃生门:直连模式可用;正常情况不需要,沉淀已自动化)

evolve-status

L6 沉淀进度与健康度查看(所有模式可用)

完整 43 个子命令说明见 hy-mem help。

配置说明

配置文件位于 config.json,支持以下配置项:

  • embedding: 嵌入模型配置(provider、model、apiKey)

  • llm: 大语言模型配置。S1 抽取模型,推荐分析类小模型(信息抽取、场景分类等封闭判定需求),如 tongyi-xiaomi-analysis-flash —— 高频调用,快和便宜优先,不要求开放生成能力

  • evolve: L6 归纳配置(model / maxTokens 8000 / schemaLimit 3 / schemaMinScore 0.25 / language)。model 是 S2 归纳模型,推荐更强的通用大模型(如 deepseek-v4.1-flash)—— 开放归纳是成败关键,分析类小模型做不了(实测只回 7 个 token 还自报 success);留空则回落 llm.model(等于没分)。schemaMinScore 默认 0.25 而非 SDK 的 0.4:evolve 归纳出的 schema 是英文,中文 query 对它的语义分实测 0.17~0.34,0.4 会全部滤空。language 控制归纳输出语言:默认 auto 跟随 SDK 检测(对技术型中文记忆失灵,实测 32 条中文事实因 ASCII 密度被判 en);config set evolve.language=zh 强制中文 schema(CLI 有 --language)——SDK ≥2.0.11 原生支持(显式语言会换归纳提示词本体 + 追加硬性输出语言约束),配 zh 后中文 query 检索分可回正常档;auto 检测上游仍未修,显式配置是推荐用法。auto 控制自动沉淀(evolve.auto):enabled=true(默认,仅 ultra)/ minNewFacts=8(自上次沉淀以来新增 L2 事实达到才跑)/ cooldownHours=24(两次尝试最小间隔,连续失败按 2^n 退避、7 天封顶,成功清零)。配置入口:config set evolve.model=… 或 setup 面板「沉淀模型」(仅 ultra 生效)

  • storage: 存储路径配置

  • user_id: 当前身份标识

  • search: 检索参数(min_score 等)

  • servePort: serve 固定端口(0=随机默认;设为固定值后 serve 重启不再换端口,长驻 MCP client 端点恒有效)

  • backend.memory: 记忆后端选择(默认 hy-memory;JDBC 式协议层,实现在 backends/,未来可注册其他实现)

  • graph: ultra 图库资源(graph.bufferPoolMb / graph.maxThreads)。留空沿用 SDK 2.0.15 默认(512MB / 4 线程),0 表示交回 Kuzu 默认(≈80% 物理内存 / 全部核)。等价环境变量 MEMORY_GRAPH_BUFFER_POOL_MB / MEMORY_GRAPH_MAX_THREADS;两处都设时 config 覆盖 env(与其它字段一致)。doctor 会回显生效值。SDK 2.0.15 起同进程多个 client 共享一个 kuzu.Database,跨进程仍受文件锁约束

密钥存储:默认直接固化在 config.json 的 apiKey 字段(config.json 恒被 .gitignore 保护,不会入库);也兼容从环境变量读取(MEMORY_EMBEDDER_API_KEY / MEMORY_LLM_API_KEY,老配置无需改动)。

项目结构

hy-mem/
├── src/hymem/              # 包根(pip install -e . 可装;python -m hymem 可跑)
│   ├── cli.py             # 门面入口(cmds/ 拆包后仅 re-export,79 行)
│   ├── cmds/              # CLI 按域拆包(base / write / read / maint / queue / config / parser / entry)
│   ├── ports/             # JDBC 式协议层:MemoryBackend Protocol + make_backend 工厂(不 import vendor)
│   ├── backends/          # 后端实现(hymemory/ 适配器:vendor import 唯一允许地)
│   ├── core/              # 核心域(无 UI 依赖,桌面/服务可复用)
│   │   ├── store.py       #   SQLite 队列与记忆库操作
│   │   ├── config.py      #   配置加载与密钥解析
│   │   ├── netprobe.py    #   出站请求唯一出口
│   │   ├── vdb_endpoint.py#   serve 按需拉起 / 端点发现与自愈
│   │   └── ...            #   presets / oplog / version 等
│   ├── ui/                # 终端交互层
│   │   ├── tui.py         #   终端组件(行编辑/菜单/确认)
│   │   ├── menu.py        #   交互式控制台
│   │   ├── setup_wizard.py#   设置向导与设置菜单
│   │   └── ...            #   helptext / i18n / skill_ops
│   └── mcp/
│       ├── server.py      # MCP 服务(9 工具,pro 下 8 个;evolve_status 仅 ultra 可见;端点失效自愈)
│       └── transport_http.py  # HTTP transport(--transport http,默认 stdio 不变)
├── skill/                 # Skill 定义
├── docs/                  # 契约文档(docs/specs/)+ 上游 bug 追踪(UPSTREAM-ISSUES.md)
├── scripts/               # 业务脚本(构建 / 上游补丁重放 / 闸门 / check_secrets / check_layering)
├── vendor/hy-memory/      # 上游 SDK 快照(gitlink,拉最新源码用)
├── tests/                 # 14 套测试(cli / ui / menu / setup / setup_ui / mcp / queue / vdb / oplog / i18n / encoding / concurrency / scene / evolve)
├── .local-test/           # 本地临时脚本(探针 / 实验 / bug 复现),整目录不入库
├── data/                  # 运行时数据(不入库,程序自建)
└── AGENTS.md             # 项目交接文档

分层铁律:core 不 import ui/mcp;ui 与 mcp 互不依赖;vendor import 只准出现在 backends/;版本号真源在 core/version.py。

开发说明

源码模式运行

python -m hymem <command> [options]

打包为可执行文件

python scripts/build_exe.py

打包产物为目录或压缩包形式分发,不建议使用 onefile 模式。

测试

python tests/test_cli.py        # CLI(162 项,含分层守护 G1/G2)
python tests/test_setup_ui.py   # 设置向导 UI 级(41 项)
# 共 14 套 921 项:cli / ui / menu / setup / setup_ui / mcp / queue / vdb / oplog /
# i18n / encoding / concurrency / scene / evolve。其中 mcp、concurrency、scene、evolve
# 会真调模型(缺密钥时显式跳过,不产出假绿)

注意事项

  • exe 与源码是两套完全独立的环境,修改代码后需重新打包

  • 写入记忆时建议一条只放一个主题,保持粒度清晰;事实型表述(而非寒暄/闲聊)才会被抽取成可检索记忆

  • 异步写入会自动拉起后台 worker,入队后可通过 queue 查看进度;入队 ≠ 立即可检索,pro 模式单条落库可达 2 分钟。retry / retry --shadow 重投后同样会按需拉起消费者(回执含 worker_spawned / worker_live);设 HY_MEM_AUTO_WORKER=0 可统一关闭自动拉起(add 与 retry 都生效,默认开启,非法值按开启并告警)

  • 密钥仅支持 ASCII 字符

版本策略

CLI 独立 semver,不与底层 hy-memory SDK 版本耦合(SDK 版本见 hy-mem doctor)。当前为 1.0.0-rc.11(Release Candidate):功能面完整、测试矩阵全绿,进入发布候选;自用验证稳定后转正 1.0.0。

对上游 SDK 的已知问题(图库锁降级被否决 / auto 语言误判 / 端点构造期冻结)建有追踪文档 docs/UPSTREAM-ISSUES.md:本仓库以补丁/自愈机制临时规避,上游修复后按文档流程退役。

声明

  • 本项目完全由 AI 生成(GLM + 人类需求方驱动开发模式),代码、测试与文档均由 AI 产出,人类负责需求定义、方案评审与验收。

  • 面向个人使用设计:单机单用户场景(SQLite + 本地向量库),未做多租户、鉴权与并发治理,不适合生产环境多用户部署。

  • 底层能力来自 Tencent Hy-Memory SDK(Apache 2.0),本项目仅在其上封装 CLI / MCP / TUI 交互层。

许可证

Apache License 2.0,见 LICENSE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory for MCP-compatible agents, enabling recall by meaning, automatic decay, trust scoring, and cross-agent handoffs.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent memory with semantic search for MCP-based AI agents, enabling them to store and recall information across sessions using vector embeddings.
      4
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Persistent memory MCP server for AI agents that stores, recalls, and searches conversation history, key-value context, and long-term entries across sessions with semantic search and FIFO queues.
      89 npm
      1
      -