EchoMe

让每个 AI，都能接住你的过去。

Switch AI, not yourself.

EchoMe 是一个面向 AI Agent 的个人记忆与项目上下文层。它统一保存工作习惯、技术偏好、项目文档、约束关系、历史决策和验证证据，让 Codex、Claude Code、Cursor 等客户端通过 MCP 获得一致、可追溯、可演进的上下文。

当前稳定版本为 v1.5.0，主题是 Reliable Context Runtime。

核心架构

点击架构图进入交互式版本。默认使用 Dark + Presentation Stage，支持节点搜索、关系追踪、缩放、主题切换和图片导出。

该图是 v1.5.0 发布快照。本工作树的后续收敛（包括移除未接入的 Redis）以当前架构文档为准，下一次发布时再生成新的版本化图，不覆盖该快照。

发布快照由 Archify 规格 生成，独立 HTML 保存在 docs/echome-architecture-v1.5.html。

核心能力

统一上下文入口

AI 默认调用 echome_context，由运行时自动完成：

• personal / project / impact / temporal 路由选择
• canonical project 与 alias 解析
• 记忆、约束、制品、事件和图关系召回
• 冲突、未知项、时效性和 answerability 判断
• token budget 控制与检索 trace 记录
• Hub 不可达时的加密、只读 last-known-good 降级

模型不需要先猜测应该使用记忆搜索、图查询还是项目上下文工具。

个人记忆

• 三轴模型：Type × Scope × Layer
• L0 全局加载、L1 项目加载、L2 MCP 按需检索
• keyword、vector、graph、temporal 多种检索证据
• active / ai_review / pending / deprecated / archived 状态管理
• derived_from、superseded_by 等可追溯关系
• feedback、temporal review 和检索质量评估

Project Knowledge

• 项目制品版本与 chunk 索引
• 版本化约束、关系边和来源证据
• Project Events 记录 issue、failure、fix、test、decision 和 deploy
• Context Compiler 按任务与改动路径生成证据优先的上下文包
• Impact 与 Preflight 在修改、测试、提交和部署前提供历史约束
• canonical project aliases 避免目录名、Git remote 和历史 ID 分裂上下文

Memory Sleep

Memory Sleep 用于整理不断增长的记忆，但不会静默覆盖历史：

1. Hub 返回所有符合条件的非归档、非 deprecated 候选。
2. 服务端或能力更强的客户端 AI 生成文本预案和 memory_sleep_plan.v1 JSON。
3. Hub 校验并展示 proposal。
4. 确认后新增归纳记忆，原记忆转为 archived，并保留派生和替代关系。

质量与可观测性

Web Console 提供：

• Memory 与 Project 工作台
• 可交互记忆关系图和节点邻居
• Retrieval Debugger 与检索日志
• Context Runs、fallback、错误与选入证据
• Memory Quality Eval 与 Project Context Eval
• Sleep session 和变更审计

Context Outcome 与 Memory Feedback 均为 append-only 信号，不会直接、静默地改变生产排序。

AI 应该如何使用 EchoMe

推荐工作流：

1. 首次接触时调用 echome_capabilities 发现能力。
2. 普通任务优先调用 echome_context。
3. 关键历史决策调用 echome_memory_explain 检查来源、替代关系和时效性。
4. 任务结束后，仅在证据明确时追加 feedback 或 context outcome。
5. 在 full profile 中，宽泛问题可使用 summary-first，项目修改可使用 preflight/impact 专业工具。

EchoMe MCP 提供 core 和 full 两种 profile。新执行 echome init / echome mcp install 的配置会显式使用 core，暴露 8 个高频入口；设置 ECHOME_MCP_PROFILE=full 并重启客户端后，可启用 summary-first、Project Knowledge 和 Sleep 等专业工具。为避免升级破坏，历史配置若没有 profile 字段会继续使用 full。

系统组件

默认 Docker Compose 端口：

安装

要求 Python 3.11 或更高版本。

pip install --upgrade echome
echome version

也可以直接从 GitHub 安装：

pip install "echome @ git+https://github.com/qzhqzh/EchoMe.git"

快速开始

1. 部署 Hub

git clone https://github.com/qzhqzh/EchoMe.git
cd EchoMe
cp hub/.env.example hub/.env
docker compose up -d

启动后访问 http://localhost:20001 使用 Web Console。

2. 初始化 CLI 与 MCP

echome init
echome doctor

echome init 会创建本地配置、连接 Hub，并注册可识别的 AI 客户端。也可以单独执行：

echome mcp install

MCP Server 默认使用 stdio：

echome mcp serve

需要本地 Streamable HTTP 时：

echome mcp serve --http --host 127.0.0.1 --port 20003

3. 添加和同步记忆

echome add
echome list
echome search "Git 提交流程"
echome sync

4. 整理记忆

echome sleep candidates

Sleep apply 需要先提交并确认合法 JSON 预案，不会直接批量重写原始记忆。

常用命令

echome push / echome pull 保留为未来的文件式 local-vault 接口，当前会明确返回“未实现”，不会执行空同步并伪报成功。

数据安全原则

• PostgreSQL + pgvector 是唯一权威服务端数据层。
• 数据库迁移采用 Alembic；v1.5 当前 schema revision 为 015。
• archived 和 deprecated 记忆不会作为当前有效事实参与默认检索。
• Sleep、项目重关联和约束复核采用 proposal → validate → apply。
• 原始记忆、制品版本、约束版本、事件和关系证据不被静默删除。
• 运行反馈先追加记录，经过离线评估后才考虑影响排序。
• Retrieval Logs 仅保存 ID、标题、分数和 trace，不复制记忆正文。
• 本地 last-known-good 缓存使用 AES-256-GCM 加密，并受账号、请求键和 TTL 约束。

开发与验证

# CLI + MCP
uv sync --extra dev
uv run pytest
uv run ruff check echome echome_mcp tests

# Hub
cd hub
uv sync --extra dev
uv run pytest
uv run ruff check app tests alembic/versions

# Web
cd ../web
npm ci
npm run build

CI 对 CLI/MCP、Hub 和 Web 分别执行 lockfile 安装、Ruff、pytest 与 production build；发布构建还会在干净虚拟环境中安装 wheel 并运行命令入口。

文档

• 系统架构
• v1.5 规划与验收
• 记忆模型
• 记忆检索设计
• Memory Sleep
• Hub API 规范
• MCP Server 规范
• 数据生命周期
• 开发路线图
• 用户指南

License

MIT