为 AI Agent 打造的分层、长期存续的记忆引擎
中文 | English
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 晋升、
projectsprovenance、文件/依赖/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/cloud.md |
安装
pip install zymor
快速开始
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 集成
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:
claude mcp add zymor -- uv run --directory <ZYMOR_REPO> zymor mcp
DSH / Claude Code 的完整配置与验收步骤见 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。
测试
最小冒烟测试只验证基础功能可用(写入/检索/读取/上下文/失效锚点/规则检查/跨项目晋升),不验证效果:
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、SECURITY.md、CODE_OF_CONDUCT.md,以及 仓库工作流。
License
Apache-2.0,见 LICENSE。
Metadata
Release files for zymor 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zymor-0.6.0.tar.gz | 355.1 kB | With provenance | Details for zymor-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| zymor-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for zymor-0.6.0-py3-none-any.whl |
Total release size: 590.2 kB
Release files / zymor-0.6.0.tar.gz
| Download URL | zymor-0.6.0.tar.gz |
|---|---|
| Size | 355.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dcbf8ebe4470f9bbe1ea48538ffa84278d4dc2f8f91fe37e3a55c8e61075317c
|
|
BLAKE2b-256 checksum How to use checksums |
e053018a3b03301773dc1a80cb3b0eec547a5c8bf12163d11972b647e9c19f12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / zymor-0.6.0-py3-none-any.whl
| Download URL | zymor-0.6.0-py3-none-any.whl |
|---|---|
| Size | 235.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
20557ef82b3afd62eb6fa521602701bbc84dc8ac4d33fa9b9241b7ad3d5979c3
|
|
BLAKE2b-256 checksum How to use checksums |
83b8e6f45c543020e0aef731a3fb50a65df28e786b83cd2e8b6840e12baf9574
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for zymor 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for zymor-0.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.