Skip to main content

Zymor Logo

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

Python License MCP Version PyPI CI Storage

中文 | 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 晋升、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/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)

Source distribution for zymor 0.6.0
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)

Table of built distributions (wheels) for zymor 0.6.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.6.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page