hy-mem
Supports OpenAI-compatible LLM and embedding APIs, enabling semantic vector search and LLM-based fact extraction for stored memories.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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工具或 CLIhy-mem evolve-status(所有模式可看)查进度与历史,get_version在连续失败时会顺带带出evolve_health异常信号。归纳模型与抽取/判重分开配(config set evolve.model=…)——抽取(llm.model)配分析类小模型(如tongyi-xiaomi-analysis-flash,封闭判定够用且快),归纳(evolve.model)配更强的通用大模型(如deepseek-v4.1-flash):弱模型能抽取但做不了开放归纳。手动逃生门:CLIhy-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基本命令
命令 | 说明 |
| 添加记忆(支持单条/多条/带标签) |
| 语义检索记忆(支持 |
| 列出 / 详情 / 修改 / 逻辑删除 |
| 彻底删除 / 清理逻辑删除残留( |
| 标签与归档管理 |
| 统计 / 19 项健康自检 |
| 异步队列查看 / 消费 / 清空 / 重投(含 shadow 影子重投) |
| 数据面快照备份 / 恢复 |
| 向量空间巡检 / 重嵌计划 / 执行重嵌 / 图重嵌 / 删除空间(换嵌入模型后迁移用) |
| 存量记忆批量回填 L4 关系图(图库重建/降级补边用) |
| 用户画像查看( |
| 启动 MCP stdio 服务 / HTTP 服务 |
| 设置菜单 / 配置管理 / 身份切换 / 注册到 PATH |
| 操作历史 / 运行日志 / Skill 安装 / 数据迁移 / 版本 |
| 手动归纳 L6 行为模式(逃生门:直连模式可用;正常情况不需要,沉淀已自动化) |
| 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides persistent, searchable memory for MCP-compatible agents, enabling recall by meaning, automatic decay, trust scoring, and cross-agent handoffs.5MIT
- AlicenseAqualityDmaintenanceProvides persistent memory with semantic search for MCP-based AI agents, enabling them to store and recall information across sessions using vector embeddings.41MIT
- AlicenseNot gradedqualityCmaintenanceEnables persistent memory for AI agents, combining episodic and semantic memory with LLM reasoning, accessible via MCP.2MIT
- FlicenseNot gradedqualityCmaintenancePersistent 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 npm1-