mnemon-dev · Grivn · Aug 11, 2026 · Aug 11, 2026
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ LLM agents forget everything between sessions. Context compaction drops critical
 Mnemon gives your agent persistent, cross-session memory — a four-graph knowledge store with intent-aware recall, importance decay, and automatic deduplication. The `mnemon` memory path remains one local binary with zero API keys and one setup command.
 
 Mnemon ships one executable with two separate surfaces. Memory stays at the
-`mnemon` root; [Agency](docs/AGENCY.md) lives at `mnemon agency ...` and adds
+`mnemon` root; [Agency Preview](docs/AGENCY.md) lives at `mnemon agency ...` and adds
 durable, project-local responsibility and effect admission to an existing Pi
 agent. Agency does not replace Memory or the Agent Runtime.
 
@@ -85,7 +85,7 @@ mnemon --version
 mnemon agency --version
 ```
 
-### Agency (Pi)
+### Agency (Preview · Pi-first)
 
 ```bash
 mnemon agency setup --runtime pi --project-root .
@@ -94,7 +94,8 @@ mnemon agency setup --runtime pi --project-root .
 Set up each project once, then use Pi normally. Agency is available on macOS
 and Linux and remains independent from Memory: `mnemon setup --target pi --yes`
 enables Memory, while the command above enables Agency. See the
-[Agency guide](docs/AGENCY.md) for its operating model and optional peers.
+[Agency guide](docs/AGENCY.md) for its operating model, Preview compatibility
+boundary, and optional peers.
 
 ### [Claude Code](https://github.com/anthropics/claude-code)
 
@@ -408,7 +409,7 @@ See [Development and Deployment](docs/DEPLOYMENT.md) for Docker, Compose, Ollama
 
 ## Documentation
 
-- [Agency](docs/AGENCY.md) — one-time Pi setup, operating model, completion semantics, and optional peers
+- [Agency Preview](docs/AGENCY.md) — maturity boundary, Pi setup, operating model, completion semantics, and optional peers
 - [Go Engineering Standard](docs/development/go-engineering-standard.md) — maintainability, concurrency, persistence, testing, and review thresholds
 - [Design & Architecture](docs/DESIGN.md) — current engine architecture, algorithms, integration design
 - [Memory Usage & Reference](docs/USAGE.md) — root Memory commands, import, receipts, and embedding support

diff --git a/docs/AGENCY.md b/docs/AGENCY.md
@@ -2,6 +2,13 @@
 
 **English** | [中文](zh/AGENCY.md)
 
+> **Status: Preview — actively evolving.** Agency has a working implementation
+> and test coverage, but is currently intended for evaluation and controlled
+> use on macOS and Linux. Its command surface, Runtime integration, protocol,
+> peer exchange, and on-disk/wire formats may change before an explicit
+> stability milestone. This maturity label applies only to Agency; Memory has a
+> separate state model and product contract.
+
 Mnemon Agency gives an existing agent durable, project-local responsibility and
 effect admission. It records what the agent is responsible for, admits only
 valid proposed changes, and returns a durable result for each proposal.

diff --git a/docs/DESIGN.md b/docs/DESIGN.md
@@ -47,10 +47,10 @@ Runtime-native integration through runtime-specific `SKILL.md`, a shared
 `guide.md`, supported hooks or extensions, agent-led memory decisions, setup
 automation, and lightweight reviewed markdown evolution.
 
-### [Mnemon Agency](AGENCY.md)
+### [Mnemon Agency Preview](AGENCY.md)
 
 How to add durable work, receipts, and optional peer collaboration to an
-existing Agent Runtime.
+existing Agent Runtime, including its current maturity and compatibility boundary.
 
 ### [8. Design Decisions & Future Direction](design/08-decisions.md)
 

diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -1,6 +1,6 @@
 # Mnemon Memory — Usage & Reference
 
-> You don't run Memory commands yourself — the agent does, driven by hooks and guided by the skill file. This document covers the root Memory CLI for understanding what the agent can do, debugging, and advanced manual operation. For durable Agent work and peer collaboration, see the [Agency guide](AGENCY.md).
+> You don't run Memory commands yourself — the agent does, driven by hooks and guided by the skill file. This document covers the root Memory CLI for understanding what the agent can do, debugging, and advanced manual operation. For durable Agent work and peer collaboration, see the [Agency Preview guide](AGENCY.md).
 
 ---
 

diff --git a/docs/mnemond/protocol.md b/docs/mnemond/protocol.md
@@ -1,5 +1,10 @@
 # mnemond protocol
 
+> **Stability: Preview.** This is the current authority contract implemented by
+> Agency, not a long-term compatibility promise. Protocol fields, persistence,
+> peer exchange, and Runtime projections may evolve until Agency declares an
+> explicit stability milestone.
+
 This document defines the small product contract behind Mnemon Agency. It is
 an architecture boundary, not an Event-sourcing requirement and not a catalog
 of built-in collaboration patterns.

diff --git a/docs/zh/AGENCY.md b/docs/zh/AGENCY.md
@@ -2,6 +2,11 @@
 
 [English](../AGENCY.md) | **中文**
 
+> **状态：Preview，持续迭代中。** Agency 已有可运行实现和测试覆盖，但当前面向
+> macOS/Linux 上的评估与受控使用。在明确宣布稳定里程碑前，其命令表面、Runtime
+> 集成、协议、Peer 交互以及磁盘/wire 格式仍可能变化。这个成熟度标签只适用于
+> Agency；Memory 拥有独立的状态模型与产品契约。
+
 Mnemon Agency 为一个项目中的 Agent 提供持久、受约束的协作状态。它不替
 Agent 规划或执行任务，而是在 Agent 提议改变状态时决定是否接纳，并留下可
 重放、可核验的结果。

diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md
@@ -45,9 +45,10 @@ Runtime 原生集成：各 runtime 的 `SKILL.md`、共享 `guide.md`、受支
 或 extension、agent 主导的记忆判断、setup 自动化，以及经过 review 的轻量
 Markdown 演化。
 
-### [Mnemon Agency](AGENCY.md)
+### [Mnemon Agency Preview](AGENCY.md)
 
-说明如何把持久工作、回执和可选 peer 协作接入已有 Agent Runtime。
+说明如何把持久工作、回执和可选 peer 协作接入已有 Agent Runtime，以及当前
+成熟度与兼容边界。
 
 ### [8. 设计决策与未来方向](design/08-decisions.md)
 

diff --git a/docs/zh/README.md b/docs/zh/README.md
@@ -20,8 +20,8 @@ LLM 智能体在会话之间会遗忘一切。上下文压缩丢失关键决策
 Mnemon 为你的 LLM 提供持久的跨会话记忆 — 四图知识存储、意图感知检索、重要度衰减、自动去重。`mnemon` 记忆路径仍是一个本地二进制，零 API 密钥，一条命令完成部署。
 
 Mnemon 只发布一个 `mnemon` 可执行文件，同时提供两套相互独立的能力：根级
-Memory 命令保存跨会话知识；`mnemon agency ...` 为项目内 Agent 提供持久、
-受约束的协作状态。Agency 以 Pi 为首个 Runtime 集成，详情见
+Memory 命令保存跨会话知识；Preview 阶段的 `mnemon agency ...` 为项目内 Agent
+提供持久、受约束的协作状态。Agency 以 Pi 为首个 Runtime 集成，详情见
 [Agency 指南](AGENCY.md)。
 
 > **Claude Max / Pro 订阅用户？** Mnemon 完全通过你现有的订阅运作——不需要额外的 API 密钥。你的 LLM 订阅*本身*就是智能层。两条命令即可完成。
@@ -85,15 +85,16 @@ mnemon --version
 mnemon agency --version
 ```
 
-### Agency（Pi）
+### Agency（Preview · Pi-first）
 
 ```bash
 mnemon agency setup --runtime pi --project-root .
 ```
 
 每个项目设置一次，之后照常使用 Pi。Agency 支持 macOS 和 Linux，并与
 Memory 保持独立：`mnemon setup --target pi --yes` 启用 Memory，以上命令启用
-Agency。工作方式与可选 peer 配置见 [Agency 指南](AGENCY.md)。
+Agency。当前成熟度与兼容边界、工作方式及可选 peer 配置见
+[Agency 指南](AGENCY.md)。
 
 ### [Claude Code](https://github.com/anthropics/claude-code)
 
@@ -360,7 +361,7 @@ make help           # 显示所有目标
 
 ## 文档
 
-- [Agency 指南](AGENCY.md) — Pi 设置、普通使用、View → Intent → Receipt 与可选 peer 协作
+- [Agency Preview 指南](AGENCY.md) — 成熟度边界、Pi 设置、View → Intent → Receipt 与可选 peer 协作
 - [Go 工程规范](../development/go-engineering-standard.md) — 可维护性、并发、持久化、测试与质量 ratchet
 - [设计与架构](DESIGN.md) — 当前 engine architecture、核心概念、算法、集成设计
 - [Memory 用法与参考](USAGE.md) — 根级 Memory 命令、导入、回执与嵌入向量支持

diff --git a/docs/zh/USAGE.md b/docs/zh/USAGE.md
@@ -1,6 +1,6 @@
 # Mnemon Memory — 用法与参考
 
-> 你不需要自己运行 Memory 命令 — agent 会在 Hook 和 Skill 指引下执行。本文档只介绍根命名空间下的 Memory CLI，供理解能力、调试和高级手动操作使用。持久 Agent 工作与 Peer 协作请参阅 [Agency 指南](AGENCY.md)。
+> 你不需要自己运行 Memory 命令 — agent 会在 Hook 和 Skill 指引下执行。本文档只介绍根命名空间下的 Memory CLI，供理解能力、调试和高级手动操作使用。持久 Agent 工作与 Peer 协作请参阅 [Agency Preview 指南](AGENCY.md)。
 
 ---
 

diff --git a/docs/zh/mnemond/protocol.md b/docs/zh/mnemond/protocol.md
@@ -1,5 +1,9 @@
 # mnemond 协议
 
+> **稳定性：Preview。** 本文是 Agency 当前实现遵循的 authority contract，
+> 不是长期兼容承诺。在 Agency 明确宣布稳定里程碑前，协议字段、持久格式、Peer
+> 交互和 Runtime 投影仍可能演进。
+
 本文定义 Mnemon Agency 背后的最小产品契约。它不是纯 Event Sourcing
 要求，也不是内置协作模式清单。