Skip to content
BranchesTags

Repository files navigation

忆核

一个给“多 agent + 多设备”场景准备的个人长期记忆底座。

让你的记忆不再绑定某个单独的 AI、某个单独的客户端、或某一台电脑。

English README · 快速开始 · 架构说明 · 宿主服务

开始这里

README 只保留产品定位、核心边界和最短起步路径；配置、接入、UI 与部署细节优先放在 docs/。

免责声明

本项目仅供学习、研究与工程参考使用，不构成任何形式的生产可用性、稳定性、安全性或合规承诺。

使用者应自行评估并承担部署、改造、接入、数据处理及由此产生的一切风险与后果。项目作者与贡献者不对因使用、误用或基于本项目进行二次开发所导致的任何直接或间接损失承担责任。

为什么会做忆核

我开发 yihe 的原因很直接：

  • 在同一台电脑上切换 Claude、Codex、OpenCode、OpenClaw 时，记忆彼此割裂
  • 在工作电脑和生活电脑之间切换时，长期记忆无法稳定同步
  • 很多已经确认过的偏好、决策、项目上下文，只能反复重新告诉不同 agent

忆核想解决的就是这个问题：

  • 让记忆先落本地，再决定是否同步到远端
  • 让 CLI、Local API、MCP、内置 React 管理台共用同一套运行时
  • 让需要额外质量控制的对话型记忆可以进入 session -> candidate -> review，而不是只能直接写正式长期库
  • 让同步状态、删除恢复、待同步项都能被直接观察，而不是继续做黑盒

与常见方案相比：

  • 相比 Mem0：忆核更强调本地所有权、可检视状态和自带同步边界
  • 相比 OpenViking 风格的 agent memory：忆核更强调 item-centric durable memory，而不是把复杂编排本身当主产品
  • 相比 Claude Memory MCP：忆核不只是一层 MCP 包装，还同时提供 CLI、本地 API、同步和内置 React 管理台

工作流一眼看懂

Capture locally -> Shared Runtime -> Optional Candidate Review -> Formal Memory -> Multi-Agent / Multi-Device Sync

它支持“先 review 再落正式 memory”，但这不是唯一入口。

常见路径可以是：

  • 先在本地接住内容
  • 如有必要，再进入 session -> candidate -> review
  • 已确认内容也可以直接成为正式 item
  • 然后再决定是否同步到其他宿主和其他设备

它解决什么问题

现实问题 忆核的处理方式
同一台电脑上，不同 agent 的记忆彼此割裂 用统一的本地记忆底座承接多个宿主
工作机和生活机的长期记忆不同步 提供本地优先、可选远端的同步路径
对话结论直接写正式库，长期越积越脏 需要额外质量控制时，可先走 session -> candidate -> review
记忆写入、删除、同步状态不透明 CLI / API / MCP / UI 共用同一套运行时，可直接检查
记忆系统绑死在某一个工具上 让 memory 从“某个产品的附属功能”变成“你自己的底座”

适用边界

  • 更适合：经常在多个 AI 宿主之间切换，或在多台电脑之间同步长期记忆的人
  • 更适合：想把偏好、约定、项目背景沉淀成 durable memory，并保留本地所有权、可观察性和回滚空间的人
  • 不太适合：只想要极简云托管 memory API，或不关心本地所有权、review 与同步边界的人

可选 Review 工作流

1. Session

原始对话、工具操作、上下文引用先被收进 session。

2. Candidate

从 session 中提炼出待审核候选记忆。

3. Review

候选进入人工或 agent 审查：

  • accept：生成新正式记忆
  • merge：并入已有正式记忆
  • reject：拒绝进入长期库

4. Item

只有经过确认的内容才进入正式记忆库；对已经明确无误的正式资产，也可以直接写入 item。

多宿主，但一套记忆底座

忆核的重点不是再做一个“新的 AI 客户端”。

而是给这些使用场景提供同一套可复用的 memory backend：

  • Claude
  • Codex
  • OpenCode
  • OpenClaw
  • Cursor
  • 其他支持 MCP / Skills / AGENTS 的宿主

入口虽然不同：

  • CLI
  • Local API
  • MCP
  • Dashboard

但底层共享的是同一套本地运行时和同一套长期记忆模型。

常见误解

yihe 和 yihe-http 是两套系统吗？

不是。通常只是客户端配置里的不同别名，底层仍是同一套运行时。

stdio MCP 和 streamable-http MCP 是两套数据吗？

不是。默认共享同一份 SQLite、向量目录、同步配置和附件状态。

“合并到这条记忆”会新建一条 memory 吗？

不会。它会更新目标 item，并把 candidate 标记为 merged。

忆核的重点是 review UI 吗？

不是。review 是为了防止长期记忆被对话噪音污染；真正的重点是跨宿主、跨设备共享 durable memory。

更完整的设计取向见：docs/openviking-borrow.zh-CN.md

管理 UI 页面、入口路由与语言说明见：docs/UI_GUIDE.zh-CN.md 宿主机常驻服务部署见：docs/HOST_SERVICES.zh-CN.md 主机配置建议见：docs/HOST_REQUIREMENTS.zh-CN.md

核心能力

  • CLI：本地写入、搜索、导入导出、删除恢复、候选评审、会话提交
  • MCP：真实 MCP server，支持 memory / sync / candidate review / session commit
  • 分层记忆：item 为正式存储；session / candidate / review 作为可选增强工作流
  • 同步：本地优先，SQLite 或 Supabase 作为远端同步后端
  • 导出：Markdown bundle 与结构化导出能力
  • 可视化检查：内置 React 管理台，以及兼容保留的 inspector / review 片段入口

Agent Skills

忆核同时提供可复用的 skill / rule files，覆盖 Skills、AGENTS 与 Cursor rules。入口文件、宿主对照和安装方式统一见：skills/yihe/README.md

5 分钟快速开始

方案 A：本地 pip 启动

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,all]"
mkdir -p ~/.yihe
cp .env.example ~/.yihe/.env
yihe serve

打开：

http://127.0.0.1:18600/ui

方案 B：Docker 本地体验

docker compose -f docker/compose.local.yml up --build

会启动：

  • Local API：http://127.0.0.1:18600
  • Sync API：http://127.0.0.1:18610

说明：

  • 这套 Docker quickstart 默认走 lexical-only，优先保证快速起服务
  • 详细说明见 docker/README.md

方案 C：Supabase 同步后端

mkdir -p ~/.yihe
cp .env.example ~/.yihe/.env

填入至少这些配置：

YIHE_SYNC_BACKEND=supabase
YIHE_SUPABASE_URL=...
YIHE_SUPABASE_SERVICE_ROLE_KEY=...
YIHE_REGISTRATION_SECRET=...

然后执行：

pip install -e ".[cloud]"
yihe verify-sync-backend
yihe serve-sync

更完整流程见：docs/SUPABASE_SETUP.zh-CN.md

方案 D：宿主机系统服务

如果你要让 Yihe / embedding 在 macOS 宿主机正常环境里长期运行，推荐：

mkdir -p ~/.yihe
cp .env.example ~/.yihe/.env
./deploy/launchd/install.sh install

这会把本地 API/UI、Sync API、MCP HTTP 都注册成 launchd 用户级系统服务。详见 docs/HOST_SERVICES.zh-CN.md。 当前运行态最终口径见 docs/RUNTIME_UNIFICATION.zh-CN.md。

Yihe 现在只有一套正式运行态，默认根目录是 ~/.yihe：

  • yihe 是本地快捷入口，默认常见场景走 stdio
  • 长驻 HTTP MCP 服务通过 yihe serve-mcp --transport streamable-http 启动
  • 某些客户端配置里会把这个 HTTP 入口命名为 yihe-http，那只是客户端里的服务别名，不是仓库内另一条独立命令
  • 两者默认共享同一份 SQLite、向量目录、同步凭证和附件状态
  • adapter ledger 默认存放在 <data_dir>/adapter-ledger/ 下
  • 需要临时切到仓库内开发态时，显式使用 YIHE_DEV_MODE=true、yihe --dev ... 或 yihe --data-dir ./data ...

开发者需要快速迭代且不想污染正式数据时，可显式使用 YIHE_DEV_MODE=true 或 --dev。此时主运行数据与 adapter ledger 会临时落到当前工作目录下的 ./data。

架构

graph TD
    U[用户 / Agent / 浏览器]
    CLI[yihe CLI]
    API[Local API]
    MCP[MCP Server]
    UI[Built-in Dashboard]

    U --> CLI
    U --> API
    U --> MCP
    U --> UI

    CLI --> SVC[Domain Services]
    API --> SVC
    MCP --> SVC
    UI --> API

    SVC --> REPO[SQLite / Session / Candidate Repositories]
    SVC --> SEARCH[FTS + Embedding + Vector]
    SVC --> SYNC[Sync Engine / Sync API]
    SYNC --> REMOTE[SQLite Remote / Supabase]
Loading

更完整说明见：docs/architecture.zh-CN.md

当前状态

  • 已完成：item CRUD、搜索、导入导出、删除恢复、可选 session -> candidate -> review 工作流、candidate merge / accept / reject、Local API / MCP / React 管理台、autosync / 手动 sync、SQLite / Supabase 双同步后端
  • 待补强：attachment 工作流、发布示例矩阵、cloud rollout / migration 说明，以及更严格的 lint / type / coverage gate

路线图见：docs/roadmap.zh-CN.md

覆盖率

Coverage Badge

覆盖率以当前 badge 与 CI / 本地验证结果为准，不再在 README 中硬编码通过数快照。

仓库结构

yihe/
├── src/yihe/   # core runtime, API, MCP, adapters, sync
├── ui/         # React 管理台
├── docs/       # 产品、部署、接入与运维文档
├── tests/      # pytest 回归与集成测试
├── docker/     # 本地与 Supabase compose 示例
└── skills/     # 可复用 agent skill pack

开发与验证

pip install -e ".[dev,all]"
pre-commit run --all-files
ruff check .
ruff format --check .
mypy src
pytest --cov=src/yihe --cov-report=term-missing

许可证

本项目使用 Apache-2.0。

About

本地优先的 AI 长期记忆底座，让 Claude、Codex、Cursor 等 Agent 在多设备间共享、审核与同步记忆。

Resources

Readme
Apache-2.0 license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages