Metadata-Version: 2.5
Name: zymor
Version: 0.6.0
Summary: The dreaming memory system for AI agents
Author: Zymor contributors
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: mcp>=1.2.0
Requires-Dist: openai>=1.40
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: eval
Requires-Dist: backoff>=2.2; extra == 'eval'
Requires-Dist: httpx>=0.28; extra == 'eval'
Requires-Dist: numpy>=1.26; extra == 'eval'
Requires-Dist: tqdm>=4.66; extra == 'eval'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/zymor-horizontal-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/zymor-horizontal-light.svg">
    <img alt="Zymor Logo" src="assets/zymor-horizontal-light.svg" width="800">
  </picture>
</p>

**为 AI Agent 打造的分层、长期存续的记忆引擎**

[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Server-6f42c1)](https://modelcontextprotocol.io/)
[![Version](https://img.shields.io/badge/Version-v0.6.0-brightgreen)](CHANGELOG.md)
[![PyPI](https://img.shields.io/pypi/v/zymor)](https://pypi.org/project/zymor/)
[![CI](https://github.com/Gyanano/zymor/actions/workflows/ci.yml/badge.svg)](https://github.com/Gyanano/zymor/actions/workflows/ci.yml)
![Storage](https://img.shields.io/badge/Storage-Markdown%20%2B%20SQLite-4b8bbe)

**中文** | [English](README.en.md)

**Zymor（织梦师）** 是一个与宿主无关的 Agent 记忆系统：经验沉淀为可检索、可纠错、可移植的分层记忆，夜间由「做梦」完成巩固、矛盾仲裁与知识升华。记忆库是纯 Markdown 事实源 + SQLite FTS5 索引，可读、可 diff、可迁移。

## 状态

**v0.6.0 — 新增对话自动捕获、云端模式与云端同步。** 当前实现覆盖：

- **记忆内核**：L0 事件流、L1 焦点、L2 胶囊、L3 知识节点、L4 人格 facet；
- **检索与上下文**：FTS5 + 标识符子词、评分/过滤、渐进披露、ATLAS/catalog；
- **写入协议**：门控、去重、状态机、审计、隐私删除；
- **做梦引擎**：NREM 巩固、认知失调仲裁、REM 联想、人格提炼；
- **Memory Loop**：规则检查/修复闭环、文件捕获、dream 历史与 `--watch`、stats 健康指标；
- **互操作**：bundle 导出/导入、`MemoryAdapter` 契约、可移植节点格式；
- **Agent Experience**：Harness Hook/Skill 契约、本地只读面板；
- **对话捕获**：Claude Code 钩子、对话文件导入、HTTP 推送；写入前脱敏；
- **云端模式**：`zymor connect` 一次接入，各台电脑自动上传对话、按消息自动取回相关记忆，提炼在服务器完成；
- **云端同步**：`zymor sync` 增量同步知识节点，`sync mirror` 下载只读副本；
- **MCP Server**：stdio / Streamable HTTP（可启用 TLS），读写与只读模式；
- **长期记忆**：跨项目 L3 晋升、`projects` provenance、文件/依赖/API 版本锚点、stale 排除、可选 embedding 语义检索与混合检索、`memory_rules` 与 `memory_rule_check`。

## 为什么是 Zymor

- **分层，而不是一锅向量**：常驻微内核（人格 facet + 当前焦点 + 活跃胶囊）加指针索引；更深的内容按需展开。
- **可纠错，不是只追加**：矛盾会被验证、替代或墓碑化，不会静默覆盖。
- **会做梦，不只是检索**：离线巩固、仲裁、跨域联想与人格提炼。
- **可渐进披露**：目录导航 + 精确检索 + 链接跳转，而不是每次把整个库塞进上下文。

## 两种用法

| | 本地模式 | 云端模式 |
| --- | --- | --- |
| 记忆存在哪 | 每台电脑的 `.zymor/vault` 与 `~/.zymor/vault` | 一台服务器 |
| 提炼在哪运行 | 本机 `zymor dream` | 服务器 |
| 多台电脑、多个工具 | 各自独立，可用 `zymor sync` 互相补齐 | 自动共用同一份记忆 |
| 接入方式 | `zymor init` + MCP（stdio） | `zymor connect <地址> --claude-code` |
| 文档 | [`docs/guide/quickstart.md`](docs/guide/quickstart.md) | [`docs/guide/cloud.md`](docs/guide/cloud.md) |

## 安装

```bash
pip install zymor
```

## 快速开始

```bash
git clone <repo> zymor && cd zymor
uv sync

cd my-project
uv run --project <repo> zymor init            # 项目库：./.zymor/vault
uv run --project <repo> zymor init --global   # 用户库：~/.zymor/vault
uv run --project <repo> zymor remember "中文检索用 CJK bigram 预分词"
uv run --project <repo> zymor search "bigram"
uv run --project <repo> zymor dream --phase all
uv run --project <repo> zymor mcp             # MCP server（stdio）
```

## 架构

```
宿主 Agent / MCP client
        │  memory_context / rules / search / semantic_search / read / ...
        ▼
┌──────────────────────────────────────────────┐
│  Zymor MCP Server                            │
│  write protocol · retrieval · dream engine   │
└──────────────────────────────────────────────┘
        │
        ▼
  .zymor/vault/                ~/.zymor/vault/
  L0 / L1 / L2 / L3            L4 + promoted L3
  Markdown facts + SQLite FTS5 index
```

- **项目库**：`<project>/.zymor/vault`；**用户库**：`~/.zymor/vault`。
- L4 人格 facet 只写用户库；L3 默认在项目库，跨项目晋升后才进用户库。
- 文件是事实源，索引是可重建缓存。

## CLI

| 命令 | 作用 |
| --- | --- |
| `zymor init [--global]` | 初始化项目库/用户库 |
| `zymor write --file PATH \| --stdin` | 写入完整 Markdown 节点 |
| `zymor remember TEXT [--category ...]` | 快速捕获一条记忆 |
| `zymor export DIR / import DIR` | 导出/导入可校验节点 bundle |
| `zymor search QUERY [--semantic]` | 检索（可选混合语义） |
| `zymor semantic QUERY` | 向量语义检索 |
| `zymor read ID` | 读取节点 |
| `zymor log --kind KIND --content TEXT` | 追加 L0 事件 |
| `zymor capture --path . [--once]` | 轮询文件变化并写入 L0 |
| `zymor ingest PATH...` | 把对话记录增量导入 L0 |
| `zymor hook capture` | 读取宿主 Hook 的 stdin，把本次会话的新对话上传到服务器或写入本地 L0 |
| `zymor hook recall` | 读取宿主 Hook 的 stdin，输出与本条用户消息相关的记忆 |
| `zymor connect URL [--claude-code]` | 把本机接到一台 Zymor 服务器：保存地址与 token，安装钩子 |
| `zymor sync [status\|push\|pull\|mirror]` | 与远端增量同步知识节点；`mirror` 把服务器的库下载成本地只读副本 |
| `zymor focus --session ID` | 查看/更新 L1 焦点 |
| `zymor index sync\|rebuild\|catalog\|embed` | 索引、目录、向量维护 |
| `zymor rules / rule-check` | 读取/执行 verified 项目规则 |
| `zymor review / answer` | 人工确认与晨间追问 |
| `zymor promote / adopt / anchor / stale` | 跨项目晋升、采纳、失效锚定 |
| `zymor dream [--phase ...]` | 运行做梦引擎。（`--history N` 查看历史，`--watch` 循环） |
| `zymor mcp` | 启动 MCP server |
| `zymor hook context` | 输出宿主会话启动上下文 |
| `zymor panel` | 启动本地只读记忆面板 |
| `zymor doctor / stats` | 自检与统计 |

## MCP 集成

```bash
uv run zymor mcp                       # stdio（本地宿主）
export ZYMOR_MCP_HTTP_TOKEN=<随机串>
uv run zymor mcp --transport http      # Streamable HTTP（本机）
uv run zymor mcp --transport http --host 0.0.0.0 \
  --tls-cert cert.pem --tls-key key.pem   # HTTPS（对外监听必须启用 TLS）
uv run zymor mcp --read-only           # 只读模式
```

Claude Code：

```bash
claude mcp add zymor -- uv run --directory <ZYMOR_REPO> zymor mcp
```

DSH / Claude Code 的完整配置与验收步骤见 [`docs/guide/mcp-integration.md`](docs/guide/mcp-integration.md)。

MCP 工具：`memory_context`、`memory_rules`、`memory_rule_check`、`memory_search`、`memory_semantic_search`、`memory_read`、`memory_browse`、`memory_links`、`memory_write`、`memory_focus`、`memory_close`、`memory_log`、`memory_answer`、`memory_dream`、`memory_promote`、`memory_adopt`、`memory_stale`。

## 测试

最小冒烟测试只验证基础功能可用（写入/检索/读取/上下文/失效锚点/规则检查/跨项目晋升），不验证效果：

```bash
uv sync --extra dev
uv run pytest tests/test_open_smoke.py -q
```

## 文档

| 路径 | 内容 |
| --- | --- |
| `docs/guide/` | 快速开始、做梦、MCP 接入、规则检查、排障 |
| `docs/guide/migration.md` | 导出/导入与 MemoryAdapter 接口 |
| `docs/guide/harness-hooks.md` | Harness Hook/Skill 契约与接入 |
| `docs/guide/capture.md` | 对话捕获：Claude Code Hook、文件导入、HTTP 推送 |
| `docs/guide/deployment.md` | 服务器部署：TLS、常驻运行、定时做梦、客户端接入 |
| `docs/guide/cloud.md` | 云端模式：接入一次，各台电脑自动上传对话、自动取回记忆，提炼在服务器完成 |
| `docs/guide/sync.md` | 云端同步：记忆留在本地，服务器只存副本；增量、多机合并、冲突与删除规则 |
| `docs/reference/configuration.md` | 配置项参考 |
| `integrations/` | Claude Code / Codex 参考接入 |
| `docs/guide/panel.md` | 本地只读记忆面板 |
| `docs/guide/validation.md` | 社区验证与问题反馈 |
| `docs/development/repository-workflow.md` | 开发、评审、发布、分支保护与协作流程 |
| `docs/development/release.md` | 版本发布、PyPI Trusted Publishing 与 tag 流程 |
| `CONTRIBUTING.md` | 贡献指南 |
| `SECURITY.md` | 安全报告流程与边界 |
| `CODE_OF_CONDUCT.md` | 行为准则 |
| `GLOSSARY.md` | 领域术语 |
| `CHANGELOG.md` | 版本变更 |

## 已知边界

- **没有常驻 daemon**：做梦由 CLI、`memory_dream` 或 `dream.auto_after_close=true` 的关闭事件触发。
- **对话捕获需要接入一次**：Claude Code 通过 Hook 自动捕获；其他工具用 `zymor ingest` 导入文件，或调用 `POST /ingest`。没有接入的宿主仍然只能靠 Agent 调用 `memory_log`。
- **单次出现的候选不会立即成为节点**：它进入待定池（默认保留 90 天），在别的会话再次出现时才写入。需要立即写入时设 `dream.eager_singletons = true`。
- **规则检查需要主动调用**：`memory_rules` 负责加载，`memory_rule_check` 负责校验；不调用就不会检查。
- **跨项目晋升是标签/人工触发的**：带 `cross-project` 标签的 verified L3 才自动晋升；`promotion.min_projects` 可加多项目门槛。
- **外部 API 版本靠本地清单**：`zymor anchor --api` 检查 repo 内的 JSON/TOML 版本清单，不轮询远端服务。
- **语义检索可选**：需要 `[embedding]` 配置并先运行 `zymor index embed`。
- **MCP HTTP auth 是静态 Bearer token**：没有过期/作用域/吊销；stdio 依赖本机信任模型。
- **一个 MCP 进程绑定一个库**：服务器部署适合放用户库；锚点、规则检查等依赖本地仓库文件的功能留在各机器的项目库。

## 贡献

见 [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`SECURITY.md`](SECURITY.md)、[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)，以及 [仓库工作流](docs/development/repository-workflow.md)。

## License

Apache-2.0，见 [`LICENSE`](LICENSE)。

