Skip to main content
Glama
Zymor MCP Server

Zymor MCP Server

by Gyanano
README.md
<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)。