hy-mem

本地长期记忆服务，为 AI Agent 提供跨会话的记忆存储与语义检索能力。基于 Tencent Hy-Memory SDK 2.0.5 构建，内置多厂商模型预设（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 (8 tools).

下载安装

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

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

功能特性

• MCP 服务：内置 stdio MCP server（8 工具：add/search/get/update/delete/list + queue_status + get_version），任何支持 MCP 的客户端（WorkBuddy / Claude Desktop / Cursor 等）即插即用
• 语义检索：基于向量相似度的记忆搜索，写入时 LLM 自动抽取事实与标签
• 异步写入：非阻塞式入队，自动拉起后台 worker 消费；队列状态全程可查（pending / dead / shadow）
• 标签管理：灵活的标签系统，支持归档与分类
• 交互式配置：设置菜单 + 首次安装向导，连通性实测通过才放行
• 多身份支持：通过 user_id 区分不同 Agent 的记忆空间

快速开始

安装依赖

pip install -r requirements.txt

初始化配置

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

python -m cli.hy_mem_cli setup

或启动交互式菜单：

python -m cli.hy_mem_cli menu

基本命令

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

配置说明

配置文件位于 config.json，支持以下配置项：

• embedding: 嵌入模型配置（provider、model、apiKey）
• llm: 大语言模型配置
• storage: 存储路径配置
• user_id: 当前身份标识
• search: 检索参数（min_score 等）

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

项目结构

hy-mem/
├── cli/                    # CLI 核心模块
│   ├── hy_mem_cli.py      # 主入口，命令解析与分发
│   ├── config.py          # 配置加载与管理
│   ├── store.py           # SQLite 数据库操作
│   ├── local_embedder.py  # 本地嵌入服务
│   ├── tui.py             # 终端交互组件
│   ├── menu.py            # 交互式菜单
│   ├── setup_wizard.py    # 设置向导
│   └── ...
├── skill/                 # Skill 定义
├── scripts/               # 业务脚本（构建 / 提交闸门 / 测试套件）
│   ├── build_exe.py      # 打包脚本
│   ├── check_secrets.py  # 提交前密钥扫描
│   ├── test_cli.py       # CLI 测试
│   └── ...
├── .local-test/           # 本地临时脚本（探针 / 实验 / bug 复现），整目录不入库
├── data/                  # 运行时数据（不入库，程序自建）
│   ├── data/             # 记忆数据（SQLite + 向量库）
│   ├── logs/             # 日志
│   └── hy_mem_queue.db   # 异步任务队列
└── AGENTS.md             # 项目交接文档

开发说明

源码模式运行

python -m cli.hy_mem_cli <command> [options]

打包为可执行文件

python scripts/build_exe.py

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

测试

python scripts/test_cli.py        # CLI（84 项）
python scripts/test_setup_ui.py   # 设置向导 UI 级（40 项）
# 共 11 套 633 项：cli / ui / menu / setup / setup_ui / mcp / queue / vdb / oplog / i18n / encoding

注意事项

• exe 与源码是两套完全独立的环境，修改代码后需重新打包
• 写入记忆时建议一条只放一个主题，保持粒度清晰；事实型表述（而非寒暄/闲聊）才会被抽取成可检索记忆
• 异步写入会自动拉起后台 worker，入队后可通过 queue 查看进度；入队 ≠ 立即可检索，pro 模式单条落库可达 2 分钟
• 密钥仅支持 ASCII 字符

版本策略

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

声明

• 本项目完全由 AI 生成（GLM + 人类需求方驱动开发模式），代码、测试与文档均由 AI 产出，人类负责需求定义、方案评审与验收。
• 面向个人使用设计：单机单用户场景（SQLite + 本地向量库），未做多租户、鉴权与并发治理，不适合生产环境多用户部署。
• 底层能力来自 Tencent Hy-Memory SDK（Apache 2.0），本项目仅在其上封装 CLI / MCP / TUI 交互层。

许可证

Apache License 2.0，见 LICENSE。