memleaf 0.1.0__tar.gz

memleaf-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to memleaf are documented here.
+
+## 0.1.0 — 2026-08-28 (GitHub tag: v0.1)
+
+- Added the local-first, dependency-free Markdown vault core with capture,
+  memory creation, deterministic search/context retrieval, statistics, and
+  rebuildable indexes.
+- Added safe vault paths, file locking/atomic writes, frontmatter handling, and
+  secret redaction for captured text.
+- Added model-backed admission, extraction, state updates with history,
+  compaction, retryable processing, and scope-aware maintenance without adding
+  runtime dependencies.
+- Added the `memleaf` initialization CLI and the `memleaf-mcp` stdio entry
+  point.
+- Added the v2 Scope Map → directory search → bounded read protocol, including
+  per-turn retrieval state, pagination, and read budgets.
+- Added a Hermes-native MemoryProvider plus MCP setup. v0.1 supports only
+  Hermes; Codex and Antigravity are not detected, configured, or scanned for models.
+- Added packaging metadata, examples, offline local installation, and CI for
+  Python 3.11–3.13.
+
+This version is intended for source installation from GitHub and is not a PyPI
+release. Host behavior still depends on supported local Agent versions, user
+trust/authorization, and an available model route.
+
+## Planned
+
+- v0.2: add Codex support.
+- Gradually support more Agent tools through their official integration and
+  authorization mechanisms. These are plans, not delivered v0.1 capabilities.

memleaf-0.1.0/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,143 @@
+# memleaf v0.1 实施计划
+
+基线：历史 v74 设计。`README.md` 与 `README.en.md` 作为对外行为契约；实现不得把 README 中尚未完成的目标描述成已发布能力。
+
+发布范围更新（2026-08-28）：v0.1 仅 Hermes。下文 Codex/反重力适配记录仅为历史，不属于本版安装或验收范围。
+
+2026-08-28 已批准的新检索与维护方案见 [v2 实施计划](V2_IMPLEMENTATION_PLAN.md)。其 Scope-only 注入、每轮 search、按需 read 和候选级维护规则取代下文旧的 3 项目录自动注入方案；旧条目保留为历史验收记录，不代表运行目录已部署新版。
+
+## 实施原则
+
+- Python 3.11+，核心运行时仅使用标准库。
+- `knowledge/` Markdown 是真实数据源；JSON 索引必须可重建。
+- MCP 为薄适配层，业务逻辑只存在于 core。
+- 所有写入采用同目录临时文件、`fsync`、原子替换；并发写通过 vault 锁串行化。
+- 处理成功前不推进轮次水位，不清理 inbox；模型失败必须可重试。
+- `memleaf init` 是一次性安装/配置入口，不引入常驻进程。
+- 保持 v74 计划文档骨架，仅在实现事实发生变化时做最小补充；README 同样只做必要更新。
+- 用户决策（2026-08-25）：推荐源码和运行根固定为 `$HOME/memleaf`，不增加 `work` 层；从其他物理目录运行 `install.sh` 必须安全失败，只有显式设置 `MEMLEAF_INSTALL_ROOT` 才允许隔离测试/开发。
+- 用户决策（2026-08-25）：只有可靠检测到 `hermes` 可执行文件时，才安装并激活官方外部 `MemoryProvider`；未检测到时不创建 Hermes provider 插件或配置，只输出诊断。
+- 用户决策（2026-08-28）：v0.1 命令安装和 `memleaf init` 仅接入 Hermes；Codex、Antigravity 保留兼容代码但不检测、不配置、不扫描模型，`--all` 也不得绕过该边界。
+- 已审核方案（2026-08-27）：自动 `context` 只返回记忆目录（ID、短标题、项目），最多 3 项，整个自动注入不超过 600 字符；不返回正文、来源或正文摘录。MCP `search` 默认返回目录，显式完整查询保留兼容；模型按需 `read`，长正文分段读取。目录曝光不计命中，正文实际读取才计命中；不改变 process 候选提炼、scope、状态更新/history 或 Markdown 存储语义。
+- 用户决策（2026-08-25）：当前只做本地完整测试，不提交、不推送、不发布 Git/PyPI。
+
+## 阶段 A：本地核心纵切
+
+交付：可安装包、vault 初始化、受限 YAML/frontmatter、事件捕获与脱敏、Markdown 记忆 CRUD、索引重建、标签/全文/作用域检索、forget、统计。
+
+建议模块：
+
+```text
+src/memleaf/
+├── __init__.py
+├── config.py
+├── models.py
+├── vault.py
+├── frontmatter.py
+├── redaction.py
+├── locking.py
+├── capture.py
+├── index.py
+├── retrieval.py
+└── service.py
+```
+
+验收：
+
+- 相同 `event_id` 重复 capture 不产生重复事件；同 session 恢复后可追加新轮次。
+- 用户预先声明“不记录”的文本不进入 inbox；常见密钥、Cookie、私钥等在落盘前被脱敏。
+- 标签多命中采用并集，随后按 scope 继承/覆盖过滤；标签无命中时才全文回退。
+- `include_history=false` 不读取历史区；todo 默认仅返回 active。
+- `forget_memory` 精确目标直接删除且不进 history；`forget_about` 含糊时只返回候选，不误删。
+- 手工修改/删除 Markdown 后，`rebuild_index()` 只反映当前文件系统状态。
+- 并发 capture 不丢事件，损坏索引可重建。
+
+## 阶段 B：记忆处理与模型路由
+
+交付：候选提取、逐条 gate、summarize、remember、当前状态更新、history、处理水位、24 小时清理、压缩、Model Router。
+
+建议模块：
+
+```text
+src/memleaf/
+├── prompts.py
+├── processing.py
+├── memory_writer.py
+├── compaction.py
+└── llm/
+    ├── base.py
+    ├── router.py
+    ├── openai_compatible.py
+    ├── claude_compatible.py
+    └── gemini.py
+```
+
+验收：
+
+- 一个完整轮次可生成 0～N 条原子记忆；assistant 未经用户确认的建议不能写成事实。
+- 显式 remember 跳过 worth gate，但仍执行整理、查重和 scope 归属。
+- 同一事实重复处理不重复写；状态变化时旧版本进入 history，新版本成为唯一活跃状态。
+- 任一模型调用、解析、knowledge 写入或索引更新失败时不推进水位、不删除 inbox。
+- 成功轮次经过 24 小时安全期后，仅在下一次自然触发时清理。
+- 达到阈值时只选低优先级约 30% 为候选；原始记忆移入 history，不做机械删除。
+- `api` 模式覆盖 OpenAI-compatible、Claude-compatible、Gemini；新安装按用户决策将密钥直接写入权限为 `0600` 的本地配置，旧 `api_key_env` 仅兼容读取。
+- `host` 使用显式注入的宿主回调；stdio MCP 无宿主回调时返回可诊断的不可用状态，`auto` 仅在已配置 API 时回退，禁止静默选择未知远程模型。
+
+## 阶段 C：MCP、初始化与宿主适配
+
+交付：按需 stdio MCP、一次性 init CLI、Codex/Hermes 探测与配置适配器、兼容保留的 Antigravity 适配器、示例、CI 与打包。
+
+建议模块：
+
+```text
+src/memleaf/
+├── mcp_server.py
+├── cli.py
+└── adapters/
+    ├── base.py
+    ├── codex.py
+    ├── hermes.py
+    └── antigravity.py
+```
+
+MCP tools：`capture`、`context`、`search`、`read`、`process`、`remember`、`forget_memory`、`forget_about`、`rebuild_index`、`stats`。
+
+验收：
+
+- `python -m memleaf.mcp_server` 可通过 stdio 完成 initialize、tools/list、tools/call；stdout 只输出协议消息，日志写 stderr/文件。
+- 每个 MCP tool 只是 core API 的参数校验和结果封装，不复制业务规则。
+- `memleaf init --all --defaults` 可重复执行且不重复写配置。
+- Codex 适配遵循官方当前配置：本地 STDIO server 通过命令启动，配置位于用户级或受信任项目级 `config.toml`；自动修改外部配置前先备份并采用原子写入。
+- Codex/Hermes 只在真机探测结果可靠时自动配置；Antigravity 在 v0.1 不检测、不配置（包括 `--all`），仅保留兼容适配器代码。
+- 构建 wheel/sdist、全量单元测试、MCP 端到端 smoke test 均通过。
+
+## 待办与问题记录：Hermes 重连后自动捕获与提炼中断
+
+- 状态：Hermes 已验证连续多轮自动 capture→process→knowledge 写入；30 秒模型请求超时、gate/summarize 契约与白名单校验诊断、DeepSeek 结构抽取与空内容有限重试自动化修复完成。下一次真实 cron 禁用验收与干净 HOME 安装验收仍待执行；历史缺失轮次不会自动回填。
+- 真实验收曾覆盖首轮 gate+summarize 成功写入，以及后续模型空内容时保留 inbox 和处理水位；当前 `diagnostic_logging=false` 且不会默认创建诊断文件。
+- 现象：`auto_process=true`，首段对话捕获了 5 个完整轮次（10 个事件），但 Hermes 在 14:39、14:41、14:43 完成的后续轮次没有继续写入 inbox；`knowledge/` 和 `history/` 均未生成记忆。
+- 证据：目标 inbox 文件最后更新于 14:30:13；`_index/processed.json` 仍停留在第 1 轮 `processing`，没有成功处理水位；Hermes 日志记录 14:19:59 的 `auto-process failed`。Hermes 自身模型请求均成功，MCP `stats` 入口可用。
+- 初步根因：Hermes provider 的 MCP 超时配置为 5 秒，首轮处理在超时后留下未清理的 processing 标记；随后 UI/provider 重连后的完整可见轮次未恢复自动捕获/处理。当前 provider 对底层 MCP 异常只记录摘要，无法直接区分超时与重连生命周期故障。
+- [x] 修复 MCP 调用超时、失败重试和 processing 标记恢复，确保模型处理较慢时 inbox 与水位仍可安全重试。短请求默认仍为 5 秒，`process` 独立使用默认 300 秒（上限 900 秒）；超时会关闭坏 MCP 子进程，下一次调用重建连接；processing marker 写入 `owner_pid`，死亡 owner 立即恢复，旧 marker 仅保留 10 分钟兼容窗口。
+- [x] 确保 Hermes UI/provider 重连或恢复同一 session 后，每个完整可见轮次仍会捕获并触发自动提炼。`on_turn_start` 的 turn number 与 user+assistant 可见文本短哈希共同组成 turn_id；provider 仅保留有界 user 指纹队列，重复完整轮次复用相同 ID 幂等；`on_session_switch` 只在 reset/rewound 时清理旧会话状态。
+- [x] 增加可诊断日志，记录 capture/process 的阶段、耗时和错误类型，但不得记录对话正文或密钥。覆盖 initialize/stats/capture_user/capture_assistant/process/context，并区分 TimeoutError、MCP tool error 与子进程退出。
+- [x] 修复自动提炼模型调用的内部 HTTP 30 秒超时与不安全错误透传：`llm.request_timeout` 默认 120 秒、范围 1～240 秒；失败按安全 code/stage 透传到 MCP、日志和 processing marker，失败后保留 inbox、不推进水位并可重试。
+- [x] 修复 DeepSeek/OpenAI JSON mode 与 gate/summarize 契约：受支持 provider 使用 JSON mode 和固定 `max_tokens`；DeepSeek gate/summarize 关闭 thinking 以避免结构抽取被推理预算占用，严格契约失败最多重试一次，空内容额外允许第 3 次；最终失败仅透传白名单 `validation_reason`、`attempt_count`，不记录模型原始输出。
+- [x] 对齐 gate/summarize 的类型、scope、todo、证据 event_key 与 reason 约束；失败增加白名单 `validation_detail`，并支持默认关闭、开启后有界 `logs/model-diagnostics.jsonl` 的结构统计诊断，不记录 prompt、正文、字段值、密钥、URL 或异常文本。
+- [x] 按 Hermes lifecycle 同时识别 `platform` 与 `agent_context`：`platform=cron` 以及 `agent_context=cron/flush/subagent` 不召回、不捕获、不执行 process；正常 primary 交互会话保持原行为。
+- [x] 保留已有 Hermes cron 历史数据；上述边界只阻断后续非用户会话污染，不删除或回填既有记录。
+- [x] 连续多轮 Hermes 交互自动 capture→process→knowledge 已由隔离真机会话验证。
+- [ ] 在干净 HOME 完成安装验收，确认上述自动链路无需手工调用 `process`/`remember`。
+- [ ] 用下一次真实 Hermes cron 运行验证其不再触发 context、capture 或 process，且不影响正常交互会话。
+
+阶段自动化曾覆盖完整 unittest、compileall 与 diff 检查，包括慢 process 超时边界、结构化输出重试、模型错误分类、重连、进程恢复、白名单诊断、敏感日志和宿主 Hook 状态。最终发布结论以当前 CI 和发布审计为准。
+
+## 本任务状态：Codex 自动宿主 Hook；Antigravity 兼容代码暂不启用
+
+- [x] 保持 v74 Core API、MCP 与 vault 数据骨架不变；新增共用 host-event 入口，复用 capture/context/process。
+- [x] 可靠检测到 Codex 时由 `init` 默认配置 Hook；配置合并可重复、先备份、原子写入，命令使用安装解释器绝对路径。Hermes 使用其原生 provider/MCP 接入。
+- [x] 保留 Codex/Antigravity 可见内容 host-event 兼容代码；v0.1 `init`/安装不检测、不配置 Antigravity，过滤与幂等逻辑不改变 Core/MCP 骨架。
+- [x] 正常 Stop 同步 process；失败保留 inbox 与待处理状态，Hook 错误不阻塞宿主结束。
+- [x] 使用脱敏合成 fixture 完成定向与全量单元测试；Codex 真机已验证可见捕获、process 与 context 调用链。安装后 Codex 状态先为 `pending_user_review`，用户需打开 `/hooks` 审核；首个合法成功 Hook 后记录 `active`/`trusted`。
+- [x] Antigravity 适配器及其官方 Hook 解析代码继续保留作兼容性测试，但 v0.1 安装不会写入 Antigravity MCP/Hook 配置，也不会声称其已接入。
+- [ ] Codex 非空跨宿主记忆召回专项验收；Antigravity 接入与真实宿主 E2E 延后到后续版本。

memleaf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 memleaf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memleaf-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include CHANGELOG.md
+include LICENSE
+include install.sh
+include README.md
+include README.en.md
+include RELEASE_CHECKLIST.md
+include RELEASE_NOTES_v0.1.md
+include IMPLEMENTATION_PLAN.md
+include V2_IMPLEMENTATION_PLAN.md
+recursive-include tests *.py
+recursive-include examples *.md *.ndjson *.py
+recursive-include integrations/hermes/memleaf *.md *.py *.yaml

memleaf-0.1.0/PKG-INFO

@@ -0,0 +1,423 @@
+Metadata-Version: 2.4
+Name: memleaf
+Version: 0.1.0
+Summary: A local-first Markdown memory core for AI agents
+Author: memleaf contributors
+License-Expression: MIT
+Keywords: ai-agents,local-first,markdown,memory
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 冥想盆 · memleaf
+
+> 一个本地优先、Markdown 驱动、面向多个 AI Agent 的共享记忆核心。
+
+[English](README.en.md) · [GitHub](https://github.com/miffyblueboo/memleaf)
+
+> **当前版本：v0.1（Python 包版本 0.1.0）。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。当前尚未发布到 PyPI。
+> **v0.1 仅支持 Hermes。** Codex 与反重力不检测、不安装、不配置，也不扫描其模型配置。
+
+## 项目定位
+
+memleaf 把 AI Agent 的长期记忆保存为用户自己拥有的本地 Markdown 文件，并让多个 Agent 共享同一个 Vault。
+
+- 不依赖向量数据库、embedding 服务或常驻后台；
+- 不要求 memleaf 账号、云端服务、云同步或遥测；
+- `knowledge/` 中的 Markdown 是当前有效记忆的事实来源；
+- 可用 Obsidian、VS Code、Vim 等普通工具直接查看和编辑；
+- 通过本地 stdio MCP 提供主动检索、读取、记忆维护等能力；
+- 核心运行时只使用 Python 标准库，要求 Python 3.11 或更高版本。
+
+memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文。当前 v2 自动路径采用“Scope Map → 候选目录 → 受控读取正文”的流程。
+
+## 当前工作流
+
+```text
+可见的 user/assistant 对话
+        │
+        ├─ capture：脱敏后写入 inbox/<source>/<session>.md
+        │
+        ├─ 自动检索入口：只注入有界 Scope Map
+        │       │
+        │       └─ Agent 选择 Scope 和 Query
+        │              └─ search：返回候选目录
+        │                    └─ read：按需读取少量关键正文
+        │
+        └─ process / remember：由模型判断并写入 knowledge/
+                                └─ 状态更新时旧版本进入 history/
+```
+
+### 自动注入和检索
+
+自动注入只包含 Scope 的标识、父级和别名，以及检索协议提示；不包含记忆 ID、标题、正文或全量历史。Scope Map 单页最多 20 项、约 2000 字符。
+
+正常用户消息的推荐链路是：
+
+1. Agent 使用当前完整会话和 Scope Map 选择检索范围与查询词；
+2. 至少调用一次 `search`；
+3. `search` 只返回候选的 `memory_id`、标题和 Scope，不直接返回正文；
+4. 只有需要引用事实时，才使用同一轮返回的 `retrieval_id` 调用 `read`；
+5. 根据读取到的关键记忆回答，不把所有候选全部读完。
+
+当前限制：
+
+- Scope Map 最多 20 项、约 2000 字符；
+- search 候选单页最多 20 项、约 4000 字符；
+- read 单页正文最多 2000 字符；
+- 受管理轮次最多读取 3 个不同记忆、累计 6000 个正文字符；
+- `retrieval_id` 必须属于当前轮次，且必须先有成功的 `search` 才能 `read`；
+- `found`、`no_match` 和工具错误是不同状态，错误不能被伪装成无匹配；
+- 旧版 `context()` 和 Python `search(view="full")` 仍为兼容接口，但不属于新的自动注入路径。
+
+Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Scope Map；Hermes 的检索门控是 Soft Gate，不能宣称阻止所有未检索回答。
+
+## 记忆提炼规则
+
+memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
+
+- `CREATE`：没有相关现存记忆，创建一条原子、可独立理解的记忆；
+- `UPDATE`：同一未来用途的现存记忆需要更新，沿用原 `memory_id`；旧内容进入 `history/`；
+- `NO_CHANGE`：只是重复、查询、临时状态、测试、审计、诊断或没有稳定复用价值，不新增记忆。
+
+额外约束：
+
+- 通常一轮产生 0～1 条记忆，而不是按句子拆分；
+- 新记忆必须有稳定标题、完整正文和合理 Scope；
+- 项目、负责人等归属不明确时延后记录，不猜测为 `global`；
+- 相同未来用途优先 UPDATE/NO_CHANGE，不重复 CREATE；
+- 用户显式要求保存时可调用 `remember`，但仍会整理、校验和去重；
+- 模型、解析、写入或索引失败时保留 inbox 和处理水位，后续可重试；
+- 自动清理有 24 小时安全期，不会因为一次处理失败就删除原始捕获。
+
+## 安装
+
+当前版本从 GitHub 源码安装，尚未发布到 PyPI。新安装使用以下命令；已有源码目录时跳过 `git clone`，先确认源码为 v0.1。默认路径是 `$HOME/memleaf`，不增加 `work` 层：
+
+```bash
+git clone --branch v0.1 --depth 1 https://github.com/miffyblueboo/memleaf.git "$HOME/memleaf"
+cd "$HOME/memleaf"
+./install.sh
+```
+
+默认安装位置：
+
+```text
+$HOME/memleaf/              # 源码和可编辑安装目录
+$HOME/memleaf/.venv/        # memleaf 虚拟环境
+$HOME/.local/bin/memleaf   # 用户级命令入口
+$HOME/.local/bin/memleaf-mcp
+$HOME/.memleaf/             # 数据 Vault，与源码目录分离
+```
+
+安装脚本不会创建额外的 `work` 层。它使用标准库在独立虚拟环境中链接源码、生成命令入口，不依赖 pip/setuptools，也不升级用户其他 Python 包。支持 macOS/Linux；自动查找 Python 3.11+，找不到时可用 `MEMLEAF_PYTHON=/path/to/python3 ./install.sh` 指定。
+
+如果只是对非标准源码目录做隔离测试，必须显式指定当前源码目录：
+
+```bash
+MEMLEAF_INSTALL_ROOT="$PWD" ./install.sh
+```
+
+### 安装时的宿主配置
+
+`install.sh` 会先初始化 `$HOME/.memleaf`，仅接入 Hermes；如果检测到可执行的 Hermes，则继续完成两条彼此独立的接入链：
+
+1. 安装并激活 Hermes 官方原生 `MemoryProvider` 插件；
+2. 通过 Hermes 官方 MCP CLI 配置 `memleaf`，并验证 MCP Server 能发现 11 个工具。
+
+Hermes 相关路径：
+
+```text
+$HOME/.hermes/plugins/memleaf/   # 用户级 provider 插件
+$HOME/.hermes/memleaf.json       # Vault、绝对 MCP 命令和超时配置
+```
+
+安装后请重启 Hermes。若安装时找不到完整可调用的聊天模型路由，交互终端会要求补充模型配置并直接写入 Vault 配置文件；非交互执行会明确返回失败，不会伪造成功状态。
+
+Codex 和 Antigravity（反重力）不属于 v0.1 范围：安装和 `memleaf init --all` 均不检测、不修改它们的 MCP、Hook 或模型配置。已有安装保持原样；源码中的兼容适配器不代表本版支持接入。
+
+### 初始化命令
+
+先查看计划变更：
+
+```bash
+memleaf init --dry-run --json
+```
+
+确认后初始化：
+
+```bash
+memleaf init --all --defaults
+```
+
+常用选项：
+
+```bash
+memleaf init --vault /path/to/vault
+memleaf init --no-hermes
+memleaf init --no-model-discovery
+memleaf init --json
+```
+
+`--no-codex` 和 `--no-antigravity` 为兼容保留的无操作参数。宿主配置只会在检测证据可靠、结构可识别且没有冲突时修改；修改前会创建备份，未知或冲突配置保持不变。
+
+## Hermes 使用方式
+
+Hermes 的原生 Provider 和 MCP Server 是两个不同入口，但共用同一个 `$HOME/.memleaf`：
+
+- Provider 负责自动捕获可见的 Hermes user/assistant 轮次，并在完整轮次后触发 `process`；
+- Provider 只提供 Scope Map，不直接注入记忆正文；
+- Agent 需要通过 MCP `search` 找到候选，再用当前 `retrieval_id` 调用 `read`；
+- MCP 仍用于主动 `search`、`remember`、`forget` 和维护操作；
+- MCP 连接失败时会关闭坏连接，后续请求可重建连接；
+- `process` 使用已发现或用户配置的模型路由执行准入判断和记忆整理；失败数据保留在 inbox 中；
+- cron、flush、subagent 等非主用户会话不会自动召回、捕获或处理。
+
+安装完成后可检查：
+
+```bash
+hermes memory status
+```
+
+正常重启 Hermes 后，原生 Provider 和 MCP 应分别显示可用。安装脚本只在 Hermes 可执行文件存在时修改 Hermes 配置；没有 Hermes 时会跳过该部分并给出提示。
+
+## MCP Server
+
+直接运行本地 stdio Server：
+
+```bash
+memleaf-mcp --vault "$HOME/.memleaf"
+```
+
+也可以使用模块入口：
+
+```bash
+python -m memleaf.mcp_server --vault "$HOME/.memleaf"
+```
+
+不传 `--vault` 时默认使用 `~/.memleaf`；也可以设置 `MEMLEAF_VAULT`。正常情况下不需要手工常驻，Hermes 会按需启动它。stdout 只输出 JSON-RPC，日志不会污染协议通道。
+
+当前提供 11 个工具：
+
+| 工具 | 用途 |
+| --- | --- |
+| `capture` | 捕获一条明确传入的可见对话事件到 inbox |
+| `context` | 旧版兼容的有界轻量目录，不用于 v2 自动注入 |
+| `scope_catalog` | 返回 Scope、父级和别名，不返回具体记忆正文 |
+| `search` | 返回有界候选目录和 `found`/`no_match` 状态 |
+| `read` | 使用当前 `retrieval_id` 分页读取选中的记忆正文 |
+| `process` | 处理完整 inbox 轮次并按准入规则提炼 |
+| `remember` | 用户明确要求时创建或更新记忆 |
+| `forget_memory` | 按精确 ID 删除一条记忆 |
+| `forget_about` | 忘记明确主题；有歧义时只返回候选 |
+| `rebuild_index` | 重建可重建的本地派生索引 |
+| `stats` | 返回 Vault 计数和诊断统计 |
+
+`search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一轮的 `retrieval_id` 完成 `search → read`；工具错误、Scope 冲突或读取预算耗尽都应如实处理。
+
+## Python API
+
+核心库没有第三方运行时依赖：
+
+```python
+from pathlib import Path
+
+from memleaf import Memleaf
+
+service = Memleaf.initialize(Path("~/.memleaf").expanduser())
+
+memory = service.create_memory(
+    title="用户偏好",
+    body="用户偏好使用本地 Markdown 保存长期记忆。",
+    tags=["preference", "memleaf"],
+    scopes=["global"],
+    type="preference",
+)
+
+for item in service.search("Markdown"):
+    print(item.memory_id, item.title)
+```
+
+常用接口：
+
+```text
+capture()             捕获可见事件
+process()             处理完整 inbox 轮次，需要模型路由
+remember()            显式保存，需要模型路由
+create_memory()       直接创建一条 Markdown 记忆
+search()              本地检索，不更新命中统计
+context()             兼容接口，返回轻量目录
+read() / read_page()  读取记忆或分页正文
+forget_memory()
+forget_about()
+rebuild_index()
+stats()
+compact()             按阈值整理低优先级记忆，需要模型路由
+```
+
+离线示例默认使用临时 Vault，不写入 `~/.memleaf`，也不访问网络：
+
+```bash
+python examples/basic_usage.py
+python examples/basic_usage.py --vault /path/to/your/vault
+```
+
+MCP stdio 示例：
+
+```bash
+python -m memleaf.mcp_server --vault /path/to/your/vault \
+  < examples/mcp_stdio.ndjson
+```
+
+## 模型路由
+
+捕获、索引、目录检索和读取可离线运行；`process()`、`remember()` 和 `compact()` 需要可用的模型能力。
+
+`llm.mode` 支持：
+
+- `auto`：优先使用显式注入的 host backend，失败后回退到完整 API 路由；
+- `host`：只使用 Python API 显式传入的宿主回调；
+- `api`：只使用本地配置的 HTTP API。
+
+`memleaf init` 仅从 Hermes 的可读取配置中寻找完整的聊天模型路由，过滤非聊天模型，并确定性选择轻量模型作为提炼模型。未发现可用路由时复用已有的有效 memleaf 配置；要保留自选路由并跳过扫描，使用 `--no-model-discovery`。不能调用的 OAuth-only 或只有模型名的配置不会被误判为可用。
+
+API 配置示例：
+
+```yaml
+llm:
+  mode: api
+  provider: deepseek
+  protocol: openai
+  base_url: https://api.deepseek.com/v1
+  api_key: your-api-key
+  model: your-chat-model
+  request_timeout: 120
+  diagnostic_logging: false
+```
+
+也兼容 `api_key_env` 配置。当前新路由可以把 API key 直接写入 Vault 的 `config.yaml`；文件权限为 `0600`，日志和状态输出不会打印 key。若使用第三方或云端模型，提炼所需的输入会按用户选择的模型调用链发送；这不是 memleaf 的云同步。
+
+支持的 HTTP 协议包括 OpenAI Chat Completions、Claude Messages、Gemini `generateContent` 及对应兼容端点。
+
+`llm.diagnostic_logging` 默认关闭。开启后只写入有界的结构统计，不保存 prompt、模型正文、字段值、密钥、URL 或异常正文。
+
+## 原生记忆源
+
+可以在 `config.yaml` 中声明 Agent 自己维护的文本或 Markdown 文件作为只读原生源：
+
+```yaml
+native_sources:
+  hermes_notes:
+    agent: hermes
+    path: /absolute/path/to/hermes-notes.md
+    share: true
+    enabled: true
+    format: markdown
+```
+
+规则如下：
+
+- 原生文件是源事实，memleaf 不修改它，也不会默认复制到 `knowledge/`；
+- 每个源必须是唯一文件，当前单文件上限为 5 MiB；
+- `share: true` 时允许其他 Agent 读取；否则仅源所属 Agent 可访问；
+- memleaf 建立有界索引，读取正文前会重新校验源文件当前内容；
+- 文件内容变化后会刷新索引，失效或缺失不会伪造旧正文。
+
+## Vault 目录
+
+默认 Vault 是 `$HOME/.memleaf`，也可以通过 `--vault` 或配置指定本地目录：
+
+```text
+$HOME/.memleaf/
+├── config.yaml                  # Vault、Agent、模型和处理配置
+├── README.md                    # Vault 说明
+├── inbox/                       # 脱敏后的原始可见对话捕获
+│   └── <source>/<session>.md
+├── knowledge/                   # 当前有效记忆，Markdown 是事实来源
+│   └── <memory_id>.md
+├── history/                     # 更新或压缩前的历史版本
+│   └── <memory_id>--<version>.md
+├── _index/
+│   ├── tags.json                # 标签、别名、关键词和链接索引
+│   ├── processed.json           # 处理水位和幂等状态
+│   ├── native_sources.json      # 原生源只读索引
+│   ├── agents.json              # 宿主检测和配置状态
+│   ├── host_ingest.json         # 宿主生命周期游标
+│   ├── retrieval_gate.json      # 有界检索轮次账本，不含查询或正文
+│   ├── retrieval_gate.lock
+│   ├── vault.lock
+│   └── compaction.json          # 压缩事务恢复账本
+└── logs/                        # 仅 diagnostic_logging=true 时创建
+    └── model-diagnostics.jsonl  # 有界结构诊断，不含模型正文
+```
+
+`knowledge/` 和 `history/` 是可读数据；`_index/` 主要是派生索引或运行状态。删除或直接修改 `_index/` 可能丢失处理水位、Hook 游标或当前检索账本；需要重建时优先使用 `rebuild_index()`。
+
+默认目录尽量使用 `0700`，文件默认明文保存。memleaf 没有内置加密层，请自行保护 Vault、备份和模型调用凭证。
+
+## 隐私与安全边界
+
+- 捕获默认只接收调用方明确传入的 user/assistant 可见文本；不捕获 system prompt、developer prompt、隐藏推理、原始工具输出或附件全文；
+- 捕获落盘前尽力脱敏常见 API key、Bearer token、Cookie、JWT 和私钥，但脱敏不是加密，也不能保证识别所有敏感信息；
+- 路径校验、符号链接检查、Vault 锁、同目录临时文件、fsync 和原子替换用于保护本地写入；
+- memleaf 不主动上传整个 Vault，也没有托管后台、遥测或账号系统；
+- 选择 API/云端模型后，模型处理输入会离开本机并发送给该提供方；
+- 旧版 `context()` 或无宿主绑定的客户端只能获得单页边界，不能宣称 v2 的跨轮硬预算。
+
+## 开发与验证
+
+要求 Python 3.11+。本地运行测试：
+
+```bash
+PYTHONPATH=src python3.11 -m unittest discover -s tests -p 'test_*.py' -v
+python3.11 -m compileall -q src tests examples
+git diff --check
+```
+
+GitHub Actions 已配置 Python 3.11、3.12、3.13 测试，以及 wheel/source distribution 构建和源码包独立测试；配置不等于远端运行已通过。构建发行包需要 `build`：
+
+```bash
+python -m pip install build
+python -m build --wheel --sdist
+```
+
+## 后续计划
+
+- **v0.2：增加 Codex 支持**，延续共享 Vault、Scope Map 和按需读取的设计。
+- 后续将逐步支持更多 Agent 工具；每个宿主遵循其官方接入与授权规范，通过验收后再开放。
+- 这些是后续计划，不属于 v0.1 已交付能力，暂不承诺具体日期。
+
+## 当前边界
+
+以下内容不应被 README 或安装结果误解为已交付能力：
+
+- 尚未发布 PyPI 正式包；
+- v0.1 仅支持 Hermes；Codex 和 Antigravity（反重力）不检测、不安装、不配置；
+- Hermes 的检索门控是 Soft Gate，不保证阻止所有未检索回答；
+- 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
+- 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
+- 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
+- `history/` 的批量清理不会被普通检索自动执行，删除操作需要明确调用维护接口。
+
+设计和阶段性实施记录：
+
+- [v0.1 发布检查](RELEASE_CHECKLIST.md)
+- [V2 实施计划](V2_IMPLEMENTATION_PLAN.md)
+- [历史实现计划](IMPLEMENTATION_PLAN.md)
+- [示例说明](examples/README.md)
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。
+
+**memleaf**
+*Your memories, in files you own.*