EchoMe

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

Switch AI, not yourself.

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

当前稳定版本为 v1.9.0，包含 Trusted Context Policy、Sleep v2 和策略校准门禁； 生产策略默认仍保持 shadow，不会由 readiness 自动开启 enforce。

核心架构

点击架构图进入交互式版本。默认使用 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 解析；同时使用 Git remote、repository root 等多个身份信号
• 未命中时返回可继续执行的结构化 project resolution；无候选静默创建，唯一候选静默补 active alias
• 显式变更既有项目主 Git remote 时仍先预览、再确认；SSH 与 HTTPS 地址按同一仓库身份识别
• 记忆、约束、制品、事件和图关系召回
• 冲突、未知项、时效性和 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 在修改、测试、提交和部署前提供历史约束
• Evidence-backed Reflect 允许强客户端 AI 生成带逐条证据和来源指纹的派生视图
• canonical project aliases 避免目录名、Git remote 和历史 ID 分裂上下文

Memory Sleep

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

1. Hub 返回所有符合条件的非归档、非 deprecated 候选。
2. 服务端或能力更强的客户端 AI 生成文本预案和 JSON；新版 MCP 默认请求带来源前置条件与 replay cases 的 v2，REST v1 继续兼容。
3. Hub 校验并运行整理前后 simulation，展示来源覆盖、token footprint 和检索回归。
4. 确认后 Hub 按最新数据重新验证，再新增归纳记忆、归档来源并保留派生和替代关系。

质量与可观测性

Web Console 提供：

• Memory 与 Project 工作台
• 可交互记忆关系图和节点邻居
• Retrieval Debugger 与检索日志
• Context Runs、fallback、错误与选入证据
• Reliability/intervention shadow trace 与真实 Retrieval Log replay
• Policy Readiness 汇总显式 policy effect，并且只授予 canary 评估资格，不自动开启 enforce
• Memory Quality Eval 与五能力 Project Context Eval
• Sleep session 和变更审计

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

AI 应该如何使用 EchoMe

推荐工作流：

1. 首次接触时调用 echome_capabilities 发现能力。
2. 普通任务优先调用 echome_context。
3. 若恢复出的候选确为同一仓库但缺少 Git identity，先用 echome_update_project_git_identity 预览，得到用户确认后再应用；不要新建重复项目。
4. 关键历史决策调用 echome_memory_explain 检查来源、替代关系和时效性。
5. 任务结束后，为已记录的 context run 追加一次 outcome；有明确证据时记录 success / partial / failed / corrected，无法判断时记录 no_signal，不打断用户。
6. 在 full profile 中，宽泛问题可使用 summary-first，项目修改可使用 preflight/impact 专业工具。
7. 需要形成长期项目 mental model 时，先调用 echome_reflect_prepare，再以原始 watermark 和逐条证据调用 echome_reflect_submit。

EchoMe MCP 提供 core 和 full 两种 profile。新执行 echome init / echome mcp install 的配置会显式使用 core，暴露 10 个高频入口（包含安全项目创建和经确认的既有 Git identity 维护工具）；设置 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；当前生产 schema revision 为 018，后续迁移继续保持 additive-only。
• 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 并运行命令入口。

文档

当前行为以源码、当前进度与能力边界及下列接口文档为准；版本计划保留当时的设计与验收快照，不代表当前待办。部署是否具备主线能力，应通过 echome_runtime_health 和 echome_capabilities 确认。

• 开发优先级与 issue 状态复核（2026-09-12）
• 系统架构
• v1.5 规划与验收
• v1.6 Trusted Context Policy 历史基线
• v1.7 Trusted Context Calibration 历史记录
• v1.8 可信记忆闭环实施记录（发布前快照）
• 记忆模型
• 记忆检索设计
• Memory Sleep
• Hub API 规范
• MCP Server 规范
• DSH 接入与兼容性检查
• 开发验证与文档契约
• 数据生命周期
• 开发路线图
• 用户指南

License

MIT