@xqli02/mneme 0.1.0 → 0.1.2

package/README.md

@@ -1,175 +1,170 @@
 # mneme
 
-面向长期工程项目的 AI Agent 上下文与记忆架构。解决 coding agent 在跨 session 工作中的状态丢失、事实遗忘和重复分析问题。
+**Three-layer memory architecture for AI coding agents.**
 
-> 架构设计详见 [ARCHITECTURE.md](ARCHITECTURE.md)
+mneme gives coding agents (like [OpenCode](https://opencode.ai)) persistent memory across sessions. It separates long-term facts, task state, and short-term execution into three distinct layers — so agents stop forgetting decisions, losing progress, and repeating work.
 
----
+## The problem
 
-## 快速开始
+AI coding agents work in sessions. Each session has a context window that fills up and gets compacted. When that happens:
 
-```bash
-# 安装
-npm install -g @xqli02/mneme
+- **Architectural decisions get forgotten.** The agent re-analyzes problems it already solved.
+- **Task progress is lost.** The agent doesn't know what it finished yesterday.
+- **Lessons disappear.** The agent hits the same pitfalls again.
 
-# 在任意项目目录下初始化
-mkdir my-project && cd my-project
-mneme init
+Prompt engineering doesn't fix this. The issue is structural: agents have no separation between things that must survive forever, things that must survive across sessions, and things that only matter right now.
 
-# 开始使用
-mneme
+## The solution: three layers
+
+```
+┌─────────────────────────────────────────┐
+│  OpenClaw   — Facts     (long-term)     │  survives forever
+├─────────────────────────────────────────┤
+│  Beads      — Tasks     (mid-term)      │  survives across sessions
+├─────────────────────────────────────────┤
+│  OpenCode   — Execution (short-term)    │  lives within one session
+└─────────────────────────────────────────┘
 ```
 
-`mneme init` 会自动完成：
-1. 安装依赖（git、dolt、bd）
-2. 初始化 git 仓库
-3. 创建三层架构文件（`.openclaw/`、`.opencode/`、`AGENTS.md`、`.gitignore`）
-4. 启动 dolt server + 初始化 beads
+| Layer | What it stores | Lifetime | Example |
+|-------|---------------|----------|---------|
+| **OpenClaw** | Verified engineering facts — architecture decisions, constraints, pitfalls | Project lifetime | "Database must use PostgreSQL" |
+| **Beads** | Task state — what's done, what's blocked, what's next | Cross-session | "Auth module: JWT signing done, verification pending" |
+| **OpenCode** | Current execution context — code analysis, file edits | Single session | "This function's third parameter is timeout" |
+
+Each layer has clear ownership. Facts can't be modified without human approval. Tasks are managed through a dependency-aware tracker. Execution context is disposable.
 
-### CLI 命令
+## Quick start
+
+Prerequisites: [Node.js](https://nodejs.org/) >= 18, [Git](https://git-scm.com/), [OpenCode](https://opencode.ai)
 
 ```bash
-mneme              # 启动 opencode TUI（等同于 mneme start）
-mneme init         # 初始化当前目录
-mneme doctor       # 检查依赖和项目健康状态
-mneme status       # 三层记忆状态总览
-mneme compact      # 压缩前持久化检查
-mneme version      # 打印版本号
-
-# OpenClaw — 长期事实管理
-mneme facts                    # 查看事实文件列表
-mneme facts --stats            # 查看行数/预算统计
-mneme facts architecture       # 查看某个事实文件内容
-mneme propose --file=pitfalls --content="..." --reason="..."  # 提议新事实
-mneme review                   # 列出待审批提议
-mneme review <id> --approve    # 批准提议，写入 facts
-mneme review <id> --reject     # 拒绝提议
-
-# Beads — 任务管理
-mneme ready                   # 查看可执行任务
-mneme list --status=open      # 列出所有未完成任务
-mneme show <id>               # 查看任务详情
-mneme create --title="..." --description="..." --type=task -p 2  # 创建任务
-mneme update <id> --notes="进度说明"  # 更新任务
-mneme close <id> --reason="完成"      # 关闭任务
-
-# OpenCode — AI agent（opencode 透传）
-mneme auto                # 自主 agent 监督循环（自动选取任务）
-mneme auto "fix the bug"  # 指定目标启动
-mneme auto --attach URL   # 连接已有 opencode 服务
-mneme run "fix the bug"   # 非交互模式运行
-mneme web                 # 启动 Web 界面
-mneme serve               # 启动 headless server
+npm install -g @xqli02/mneme
+
+cd your-project
+mneme init
+mneme
 ```
 
----
+`mneme init` sets up everything in one command:
+1. Installs [Dolt](https://www.dolthub.com/repositories) and [bd](https://github.com/steveyegge/beads) if missing
+2. Initializes a git repo (if needed)
+3. Creates the three-layer structure (`.openclaw/`, `.beads/`, `.opencode/`, `AGENTS.md`)
+4. Starts the task database
+
+That's it. Run `mneme` to launch the agent, or `mneme doctor` to verify your setup.
 
-## 自主模式 (`mneme auto`)
+## How it works
 
-`mneme auto` 启动一个自主 agent 监督循环，自动从 beads 中选取任务并驱动 opencode 完成：
+### Every session starts the same way
+
+The agent reads facts, checks tasks, picks one to focus on:
 
 ```bash
-mneme auto                          # 自动从 ready beads 中选取任务
-mneme auto "Build auth module"      # 以指定目标启动
-mneme auto --attach http://localhost:4097  # 连接已有 opencode 服务
-mneme auto --port 4097              # 指定服务端口
-mneme auto --max-turns 50           # 限制最大轮次
+mneme facts              # Read long-term facts (agent does this automatically)
+mneme ready              # See which tasks have no blockers
+mneme update <id> --status=in_progress   # Claim a task
 ```
 
-运行时可随时输入：
-- **任意文本** — 在下一轮注入反馈给 agent
-- `/status` — 查看当前任务状态
-- `/skip` — 跳过当前 bead
-- `/quit` — 停止并退出
+### During work
 
-工作流程：
-1. 启动（或连接）opencode serve 后端
-2. 注入系统上下文（AGENTS.md + OpenClaw facts）
-3. 从 `mneme ready` 选取最高优先级 bead
-4. Claim bead → 构造 prompt → 发送给 opencode
-5. 流式展示 agent 进度
-6. 完成后自动选取下一个 bead
-7. 无可执行 bead 时等待用户输入
+The agent records progress and creates sub-tasks as it goes:
 
----
+```bash
+mneme update <id> --notes="Implemented JWT signing, discovered need for refresh tokens"
+mneme create --title="Add refresh token support" --type=task -p 2
+```
 
-## 三层记忆架构
+### When done
 
-| 层 | 工具 | 职责 | 生命周期 |
-|---|---|---|---|
-| OpenClaw | `.openclaw/facts/*.md` | 不能忘的事实 | 跨项目 |
-| Beads | [bd](https://github.com/steveyegge/beads) | 不能断的进度 | 跨 session |
-| OpenCode | 对话上下文 | 当下的执行 | 单 session |
+```bash
+mneme close <id> --reason="JWT auth complete with signing and verification"
+```
 
-## 项目结构
+### New facts require approval
 
-`mneme init` 创建的文件：
+Agents can propose facts, but only humans can approve them:
 
-```
-.openclaw/facts/         长期事实（架构、约束、红线、陷阱）
-.openclaw/proposals/     待审批的事实提议（mneme propose 创建）
-.beads/                  任务状态（由 bd 管理）
-.opencode/prompt.md      Session 启动 prompt
-AGENTS.md                Agent 行为规则
-.gitignore               排除 dolt 数据等运行时文件
+```bash
+mneme propose --file=architecture --content="Auth uses JWT with RS256" --reason="Decided after evaluating HMAC vs RSA"
+mneme review                    # Human reviews pending proposals
+mneme review <id> --approve     # Write to facts
 ```
 
-## Session 工作流
+### Autonomous mode
 
-```bash
-# 1. 读取长期事实（agent 自动执行）
-mneme facts
+`mneme auto` runs a supervisor loop that picks tasks and drives the agent continuously:
 
-# 2. 查看可执行任务
-mneme ready
+```bash
+mneme auto                      # Auto-pick from ready tasks
+mneme auto "Build auth module"  # Start with a specific goal
+```
 
-# 3. Claim 一个任务
-mneme update <id> --status=in_progress
+Type feedback anytime while it runs. `/status` to check progress, `/quit` to stop.
 
-# 4. 工作、记录进度
-mneme update <id> --notes="完成了 X，发现了 Y"
+## CLI reference
 
-# 5. 完成
-mneme close <id> --reason="Done"
 ```
+mneme                           Launch agent (OpenCode TUI)
+mneme init                      Initialize mneme in current directory
+mneme doctor                    Check dependencies and project health
+mneme status                    Three-layer memory dashboard
+mneme auto [goal]               Autonomous agent supervisor
+
+mneme facts [name] [--stats]    View long-term facts
+mneme propose --file=... ...    Propose a new fact
+mneme review [id] [--approve]   Review pending proposals
+
+mneme ready                     Tasks with no blockers
+mneme list [--status=STATUS]    List tasks
+mneme show <id>                 Task details
+mneme create --title="..."      Create a task
+mneme update <id> [--notes=..]  Update a task
+mneme close <id> [--reason=..]  Close a task
+mneme blocked                   Show blocked tasks
+mneme dep add <child> <parent>  Add dependency
+
+mneme run [message]             Run agent non-interactively
+mneme serve                     Start headless server
+mneme compact                   Pre-compaction persistence check
+mneme version                   Print version
+```
+
+## Project structure
 
-## 什么信息放哪一层？
+After `mneme init`, your project contains:
 
 ```
-新信息产生
-  │
-  ├─ 6 个月后还有用？
-  │    ├─ YES + 事实/约束/教训 → OpenClaw（提议写入，需人工确认）
-  │    ├─ YES + 待办/进度     → Beads（直接写入）
-  │    └─ NO → 下个 session 需要？
-  │         ├─ YES → Beads
-  │         └─ NO  → 留在 OpenCode，不持久化
+.openclaw/
+  facts/                 Long-term facts (architecture, constraints, pitfalls)
+  proposals/             Pending fact proposals awaiting human review
+.beads/                  Task database (managed by bd, backed by Dolt)
+.opencode/
+  prompt.md              Session startup prompt for the agent
+AGENTS.md                Agent behavior rules and routing logic
 ```
 
-| 信息示例 | 写入层 |
-|---|---|
-| "数据库必须用 PostgreSQL" | OpenClaw `mneme propose --file=architecture` |
-| "禁止在生产环境直接改数据" | OpenClaw `mneme propose --file=invariants` |
-| "需要实现用户认证模块" | Beads `mneme create` |
-| "函数第 3 个参数是 timeout" | 不写，留在 OpenCode |
+## What mneme is
+
+- A CLI that unifies agent execution, task tracking, and fact management
+- A structure that gives agents persistent memory without custom infrastructure
+- A workflow where humans stay in control of long-term decisions
 
-## 核心文件说明
+## What mneme is not
 
-### `.openclaw/facts/`
+- Not a new AI model or agent — it wraps [OpenCode](https://opencode.ai)
+- Not a RAG system — facts are curated, not retrieved from embeddings
+- Not a framework — it's a single CLI with zero npm dependencies
+- Not opinionated about your code — it only manages agent memory
 
-存放已确认的长期工程事实，agent 不可单方面修改。
+## Example
 
-| 文件 | 内容 |
-|---|---|
-| `architecture.md` | 架构决策 |
-| `invariants.md` | 不可违反的约束与红线 |
-| `performance_rules.md` | 性能规则 |
-| `pitfalls.md` | 已知陷阱与教训 |
+See [examples/basic/](examples/basic/) for a complete example of what a mneme-managed project looks like after initialization, with realistic facts filled in for a hypothetical todo-api project.
 
-### `AGENTS.md`
+## Architecture
 
-定义 agent 的 session 启动流程、执行规则、三层路由决策树、compaction 前动作和禁止行为。
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design document.
 
-### `.opencode/prompt.md`
+## License
 
-每个新 session 的启动 prompt，引导 agent 按正确顺序建立上下文。
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xqli02/mneme",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Three-layer memory architecture for AI coding agents (OpenClaw + Beads + OpenCode)",
   "type": "module",
   "bin": {

package/src/commands/doctor.mjs

@@ -3,8 +3,7 @@
  */
 
 import { has, run, log, color } from "../utils.mjs";
-import { existsSync } from "node:fs";
-import { readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 
 /**
  * Check a single dependency. Returns true if OK.
@@ -20,13 +19,21 @@ function checkCmd(name, versionCmd) {
 }
 
 /**
- * Check if dolt server is reachable by bd.
+ * Check if dolt server is reachable by bd. Show which database is in use.
  */
 function checkDoltServer() {
   if (!has("bd")) return false;
   const result = run("bd list --status=open 2>&1");
   if (result !== null && !result.includes("unreachable") && !result.includes("Error")) {
-    log.ok("dolt server reachable");
+    // Show which database this project uses
+    let dbInfo = "";
+    if (existsSync(".beads/metadata.json")) {
+      try {
+        const meta = JSON.parse(readFileSync(".beads/metadata.json", "utf-8"));
+        if (meta.dolt_database) dbInfo = ` ${color.dim(`(db: ${meta.dolt_database})`)}`;
+      } catch { /* ignore */ }
+    }
+    log.ok(`dolt server reachable${dbInfo}`);
     return true;
   }
   log.warn("dolt server not running or not reachable");

package/src/commands/init.mjs

@@ -221,24 +221,34 @@ function installBd() {
 
 // ── Dolt server + bd init ───────────────────────────────────────────────────
 
+/**
+ * Shared dolt data directory. All projects store their databases here,
+ * isolated by database name (e.g. beads_projectA, beads_projectB).
+ * One dolt server on port 3307 serves all projects on this machine.
+ */
+const DOLT_DATA_DIR = process.env.MNEME_DOLT_DATA_DIR
+  || join(process.env.HOME, ".dolt", "databases");
+
+const DOLT_PORT = parseInt(process.env.MNEME_DOLT_PORT || "3307", 10);
+
 function ensureDoltServer() {
-  // Check if bd can already talk to dolt
+  if (!existsSync(DOLT_DATA_DIR)) {
+    mkdirSync(DOLT_DATA_DIR, { recursive: true });
+  }
+
+  // Check if a dolt server is already running and reachable
   const test = run("bd list --status=open 2>&1");
   if (test !== null && !test.includes("unreachable") && !test.includes("connection refused")) {
-    log.ok("dolt server already running");
+    log.ok(`dolt server already running ${color.dim(`(port ${DOLT_PORT})`)}`);
     return true;
   }
 
-  log.info("Starting dolt server...");
-  const dataDir = existsSync(".beads/dolt") ? ".beads/dolt" : `${process.env.HOME}/.dolt/databases`;
-
-  if (!existsSync(dataDir)) {
-    mkdirSync(dataDir, { recursive: true });
-  }
+  log.info(`Starting dolt server (port ${DOLT_PORT}, data-dir ${DOLT_DATA_DIR})...`);
+  const logFile = join(DOLT_DATA_DIR, "server.log");
 
-  // Start in background
+  // Start in background — shared data dir, all project databases coexist
   run(
-    `nohup dolt sql-server --host 127.0.0.1 --port 3307 --data-dir "${dataDir}" > /tmp/dolt-server.log 2>&1 &`,
+    `nohup dolt sql-server --host 127.0.0.1 --port ${DOLT_PORT} --data-dir "${DOLT_DATA_DIR}" > "${logFile}" 2>&1 &`,
   );
 
   // Wait for server to be ready (up to 10s)
@@ -246,12 +256,12 @@ function ensureDoltServer() {
     run("sleep 1");
     const check = run("bd list --status=open 2>&1");
     if (check !== null && !check.includes("unreachable") && !check.includes("connection refused")) {
-      log.ok("dolt server started");
+      log.ok(`dolt server started ${color.dim(`(port ${DOLT_PORT})`)}`);
       return true;
     }
   }
 
-  log.fail("dolt server failed to start. Check /tmp/dolt-server.log");
+  log.fail(`dolt server failed to start. Check ${logFile}`);
   return false;
 }
 

package/src/templates/AGENTS.md

@@ -1,259 +1,258 @@
-# AGENTS.md — OpenCode Agent 行为规则
+# AGENTS.md
 
-## 身份与定位
+Rules for AI coding agents operating within a mneme-managed project.
 
-你是一个长期工程项目中的执行 agent。你**不承担长期记忆**，也**不承担任务管理**。你的记忆和任务状态分别由 OpenClaw 和 Beads 管理。
+This file is read by the agent at the start of every session. It defines what agents are allowed to do, what they are not allowed to do, and how to prioritize conflicting information.
 
----
+## Context priority order
 
-## Session 启动流程（必须严格遵守）
+When information conflicts, resolve it using this priority chain (highest first):
 
-每个新 session 开始时，按以下顺序执行：
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 (highest) | **OpenClaw facts** (`.openclaw/facts/`) | "Database must use PostgreSQL" |
+| 2 | **This file** (AGENTS.md) | "Never skip the startup sequence" |
+| 3 | **Beads task state** (`mneme ready`, `mneme list`) | "Auth module is in progress" |
+| 4 | **User instructions** in the current session | "Focus on the auth module first" |
+| 5 (lowest) | **Agent reasoning** and conversation history | "I think we should use SQLite" |
 
-1. **读取 OpenClaw facts（长期事实）**
-   - 阅读 `.openclaw/facts/` 下的所有文件
-   - 这些内容优先级**高于**你的推理和对话历史
-   - 若发现 facts 与当前情况矛盾，**提出质疑**而非直接修改
+If an agent's reasoning contradicts an OpenClaw fact, the fact wins. If the agent believes the fact is outdated, it must raise the contradiction to the user rather than silently overriding it.
 
-2. **读取 Beads 当前任务列表**
-   - 执行 `mneme ready` 查看当前可执行的任务
-   - 执行 `mneme list --status=open` 查看所有未完成任务
-   - 了解当前所有未完成任务及其状态和依赖关系
+## What agents are allowed to do
 
-3. **选择一个 bead 作为本 session 的 focus**
-   - 只选一个，不要同时推进多个不相关任务
-   - 优先从 `mneme ready` 的结果中选择（无阻塞依赖的 open 状态 bead）
+### Read from all three layers
 
-4. **开始执行**
+- Read all files in `.openclaw/facts/` at session start
+- Run `mneme ready` and `mneme list` to check task state
+- Read any project file needed for the current task
 
----
+### Manage tasks through mneme
 
-## 执行过程中的规则
+- Claim a task: `mneme update <id> --status=in_progress`
+- Record progress: `mneme update <id> --notes="what was done"`
+- Create sub-tasks: `mneme create --title="..." --description="..." --type=task -p 2`
+- Add dependencies: `mneme dep add <child> <parent>`
+- Close completed work: `mneme close <id> --reason="what was accomplished"`
 
-### Beads 管理
+### Propose facts (with human approval)
 
-- 开始工作前先 claim 任务：`mneme update <id> --status=in_progress`
-- 完成一个阶段性目标后，更新对应 bead 的 `notes`：`mneme update <id> --notes="进度说明"`
-- **不要依赖对话历史记住进度**，所有进度必须写入 Beads
-- 新发现的子任务应创建为新的 bead：`mneme create --title="..." --description="..." --type=task -p 2`
-- 关联发现的工作：`mneme dep add <new-id> <parent-id>`
-- **WARNING**: 禁止使用 `bd edit`，它会打开交互式编辑器。始终使用 `mneme update` 加参数
+- Propose new long-term facts: `mneme propose --file=<name> --content="..." --reason="..."`
+- A proposal must specify: which facts file, the exact content, and why it qualifies as a long-term fact
+- The proposal is not written to facts until a human approves it via `mneme review`
 
-### OpenClaw 管理
+### Execute code operations
 
-- 在执行过程中若发现新的长期事实（架构决策、红线、陷阱等），**提议**写入 OpenClaw
-- 提议需明确说明：
-  - 写入哪个 facts 文件
-  - 具体内容
-  - 为什么这是一个"长期事实"而非临时结论
-- **等待人工确认后才能写入**
+- Read, analyze, and modify code files
+- Run commands (build, test, lint, etc.)
+- Create commits and push to remote
+- All code operations must serve the current focused task
 
-### 代码操作
+### Persist state before compaction
 
-- 只负责代码分析、文件修改、命令执行等即时操作
-- 所有操作应服务于当前 focus bead 的目标
+When context is getting long or a milestone is reached:
+- Flush confirmed conclusions to Beads: `mneme update <id> --notes="..."`
+- Propose any discovered facts to OpenClaw
+- Close completed tasks or update notes with current progress and blockers
+- Then allow compaction to proceed
 
----
+### Complete sessions cleanly
 
-## 三层路由决策（自动分类）
-
-在工作过程中，你会不断产生新的信息。**你必须主动判断每条信息属于哪一层**，而不是等待用户指示。以下是决策逻辑：
-
-### 决策树
-
-```
-新信息产生
-  │
-  ├─ 问："6 个月后这条信息还有用吗？"
-  │    │
-  │    ├─ YES → 问："这是一个事实/约束/教训，还是一个待办/进度？"
-  │    │    │
-  │    │    ├─ 事实/约束/教训 → **OpenClaw**（提议写入，等待确认）
-  │    │    │
-  │    │    └─ 待办/进度 → **Beads**（直接写入）
-  │    │
-  │    └─ NO → 问："下个 session 需要这条信息吗？"
-  │         │
-  │         ├─ YES → **Beads**（写入 notes 或创建新 bead）
-  │         │
-  │         └─ NO → **OpenCode**（留在当前上下文，不持久化）
-```
+Before ending a session:
+1. Create tasks for any remaining work: `mneme create`
+2. Run quality gates if code changed (tests, linters, builds)
+3. Close finished tasks, update in-progress tasks with notes
+4. Push to remote — this is mandatory:
+   ```bash
+   git pull --rebase
+   git push
+   git status  # Must show "up to date with origin"
+   ```
+5. If push fails, resolve and retry until it succeeds
 
-### 分类示例
+## What agents are not allowed to do
 
-| 信息                                         | 分类      | 动作                                           |
-|----------------------------------------------|-----------|------------------------------------------------|
-| "这个项目用 Dolt 作为数据库后端"             | OpenClaw  | 提议写入 `facts/architecture.md`               |
-| "禁止在生产环境直接修改 Dolt 数据"           | OpenClaw  | 提议写入 `facts/invariants.md`                 |
-| "`bd edit` 会打开交互式编辑器导致 agent 卡住"| OpenClaw  | 提议写入 `facts/pitfalls.md`                   |
-| "需要实现用户认证模块"                       | Beads     | `mneme create --title="实现用户认证" ...`      |
-| "认证模块完成了 JWT 签发部分，还差验证"      | Beads     | `mneme update <id> --notes="JWT 签发完成..."` |
-| "这个函数的第 3 个参数是 timeout"            | OpenCode  | 不持久化，仅在当前操作中使用                   |
-| "正在对比两种实现方案的 trade-off"           | OpenCode  | 不持久化，除非最终选择成为架构决策             |
+### Never skip the startup sequence
 
-### 自动路由规则
+Every session must begin with:
+1. Read `.openclaw/facts/` (all files)
+2. Run `mneme ready` and `mneme list --status=open`
+3. Pick one task as the session focus
+4. Begin work
 
-1. **架构决策** → 一旦做出并确认，提议写入 `facts/architecture.md`
-2. **红线/约束** → 发现不可违反的规则时，提议写入 `facts/invariants.md`
-3. **踩坑经验** → 遇到非显而易见的陷阱时，提议写入 `facts/pitfalls.md`
-4. **性能基准** → 发现关键性能约束时，提议写入 `facts/performance_rules.md`
-5. **新任务/子任务** → 发现需要做的工作时，`mneme create` 创建 bead
-6. **进度更新** → 完成阶段性目标时，`mneme update --notes` 记录
-7. **临时分析** → 代码分析、调试过程、方案对比 → 留在 OpenCode，不持久化
+Skipping any step is prohibited. Do not start coding before reading facts and tasks.
 
-### 写入 OpenClaw 的门槛检查
+### Never modify OpenClaw facts directly
 
-在提议写入 OpenClaw 前，必须通过以下所有检查：
+- Do not edit, delete, or overwrite files in `.openclaw/facts/`
+- Do not write unverified hypotheses, temporary conclusions, or speculative analysis to facts
+- The only path to changing facts is `mneme propose` followed by human `mneme review --approve`
 
-- [ ] 这条信息已被验证（不是假设或推测）
-- [ ] 这条信息在未来 session 中会被反复需要（不是一次性的）
-- [ ] 这条信息不会快速过时（不是某个临时状态）
-- [ ] 现有 facts 文件中没有等价信息（避免重复）
+### Never recover state from conversation history
 
-只有全部通过才提议写入。提议后仍需等待人工确认。
+- Do not reconstruct task progress from earlier messages in the conversation
+- All task state must come from Beads (`mneme list`, `mneme show`)
+- If a bead's notes are empty, ask the user rather than guessing from context
 
----
+### Never work on multiple unrelated tasks
 
-## Compaction 前的固定动作
+- Each session focuses on one task (one bead)
+- Do not switch between unrelated tasks within a single session
+- If a new urgent task is discovered, create it as a bead and let the next session pick it up
 
-当感知到上下文即将过长，或在完成阶段性目标后，执行以下步骤：
+### Never create vague tasks
 
-1. **持久化已确认的结论**
-   - 将本 session 中已确认的结论更新到对应 bead：`mneme update <id> --notes="结论"`
+- Every bead must have a clear, verifiable completion condition
+- Bad: "Improve performance" — no way to know when it's done
+- Good: "Reduce API response time below 200ms for /users endpoint"
 
-2. **提议新的长期事实**
-   - 若发现应加入 OpenClaw 的内容，提出提议
+### Never use bd edit
 
-3. **更新 bead 状态**
-   - 若当前 bead 已完成，关闭它：`mneme close <id> --reason="完成说明"`
-   - 若未完成，确保 `notes` 中记录了当前进度和卡点
+- `bd edit` opens an interactive editor (`$EDITOR`), which hangs non-interactive agents
+- Always use `mneme update <id>` with flags (`--notes`, `--status`, `--title`, `--description`)
 
-4. **允许 compaction**
+### Never use markdown TODOs for task tracking
 
-> 原则：**可以丢失推理过程，但不能丢失状态与事实**
+- All task tracking goes through mneme/beads
+- Do not create TODO lists in markdown files, code comments, or any other format
+- Do not use external issue trackers
 
----
+### Never stop before pushing
 
-## 禁止行为
+- Work is not complete until `git push` succeeds
+- Do not say "ready to push when you are" — push immediately
+- If push fails, resolve the conflict and retry
 
-- 禁止跳过 session 启动流程直接开始工作
-- 禁止从对话历史恢复任务进度
-- 禁止单方面修改或删除 OpenClaw facts
-- 禁止在一个 session 中同时推进多个不相关的 bead
-- 禁止将未验证的假设写入 OpenClaw
-- 禁止创建模糊的、无法验证完成与否的 bead
-- 禁止使用 `bd edit`（会打开交互式编辑器）
+## Session lifecycle
 
-<!-- BEGIN BEADS INTEGRATION -->
-## Issue Tracking with mneme (beads)
+### 1. Startup
 
-**IMPORTANT**: This project uses **mneme** (backed by bd/beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
+```bash
+# Read long-term facts
+cat .openclaw/facts/*.md
 
-### Why beads?
+# Check available work
+mneme ready
+mneme list --status=open
+mneme list --status=in_progress
 
-- Dolt-Powered: Version-controlled SQL database with cell-level merge and native branching
-- Dependency-aware: Track blockers and relationships between issues
-- Agent-optimized: JSON output (`--json`), ready work detection, hash-based IDs
-- Zero conflict: Hash-based IDs (`bd-a1b2`) prevent merge collisions
-- Compaction: Semantic "memory decay" summarizes old closed tasks
+# Claim a task
+mneme update <id> --status=in_progress
+```
 
-### Essential Commands
+### 2. Execution
 
-**Finding work:**
+Work on the focused task. After each milestone:
 
 ```bash
-mneme ready                           # Show issues with no open blockers
-mneme list --status=open              # All open issues
-mneme list --status=in_progress       # Your active work
-mneme show <id>                       # Detailed issue view with dependencies
+mneme update <id> --notes="Completed X. Next step: Y."
 ```
 
-**Creating issues:**
+If you discover a sub-task:
 
 ```bash
-mneme create --title="Issue title" --description="Context" --type=task -p 2
-mneme create --title="Bug found" --description="Details" --type=bug -p 1
+mneme create --title="Sub-task title" --description="Context" --type=task -p 2
+mneme dep add <new-id> <parent-id>
 ```
 
-**Claiming and updating:**
+### 3. Pre-compaction
 
-```bash
-mneme update <id> --status=in_progress      # Claim work
-mneme update <id> --notes="Progress notes"  # Add notes
-mneme update <id> --title="New title"       # Update title
-mneme update <id> --description="Updated"   # Update description
-```
+When context is growing long or you've finished a milestone:
 
-**Dependencies:**
+1. Write confirmed conclusions to Beads notes
+2. Propose any new facts via `mneme propose`
+3. Close completed tasks or update notes with blockers
 
-```bash
-mneme dep add <child> <parent>        # child depends on parent
-mneme blocked                         # Show all blocked issues
-```
+Principle: **you can lose the reasoning, but you must not lose the state or the facts.**
 
-**Completing work:**
+### 4. Completion
 
 ```bash
-mneme close <id> --reason "Done"      # Close single issue
-mneme close <id1> <id2> ...           # Close multiple at once
+# Close finished work
+mneme close <id> --reason="Summary of what was done"
+
+# Create tasks for remaining work
+mneme create --title="Follow-up" --description="..." --type=task -p 2
+
+# Push everything
+git pull --rebase && git push
 ```
 
-### Issue Types
+## Information routing
 
-- `bug` - Something broken
-- `feature` - New functionality
-- `task` - Work item (tests, docs, refactoring)
-- `epic` - Large feature with subtasks
-- `chore` - Maintenance (dependencies, tooling)
+When you encounter new information, classify it immediately:
 
-### Priorities
+```
+New information
+  │
+  ├─ Will this matter in 6 months?
+  │    ├─ Yes + it's a fact/constraint/lesson  → Propose to OpenClaw
+  │    ├─ Yes + it's a task or progress update → Write to Beads
+  │    └─ No  → Will the next session need it?
+  │              ├─ Yes → Write to Beads (notes or new task)
+  │              └─ No  → Keep in context, don't persist
+```
 
-- `0` / `P0` - Critical (security, data loss, broken builds)
-- `1` / `P1` - High (major features, important bugs)
-- `2` / `P2` - Medium (default)
-- `3` / `P3` - Low (polish, optimization)
-- `4` / `P4` - Backlog (future ideas)
+| Information | Layer | Action |
+|---|---|---|
+| "This project uses event sourcing" | OpenClaw | `mneme propose --file=architecture` |
+| "Never call the payments API without idempotency keys" | OpenClaw | `mneme propose --file=invariants` |
+| "Batch size over 1000 causes OOM" | OpenClaw | `mneme propose --file=performance_rules` |
+| "The config parser silently drops unknown keys" | OpenClaw | `mneme propose --file=pitfalls` |
+| "Need to add rate limiting to the API" | Beads | `mneme create --title="Add API rate limiting"` |
+| "Rate limiting: token bucket implemented, need tests" | Beads | `mneme update <id> --notes="..."` |
+| "This function returns null on line 47" | Context | Don't persist |
 
-### Workflow for AI Agents
+### Proposing facts: threshold check
 
-1. **Check ready work**: `mneme ready` shows unblocked issues
-2. **Claim your task**: `mneme update <id> --status=in_progress`
-3. **Work on it**: Implement, test, document
-4. **Discover new work?** Create linked issue with `mneme create` + `mneme dep add`
-5. **Complete**: `mneme close <id> --reason "Done"`
+Before proposing a fact, verify all four conditions:
 
-### Important Rules
+- [ ] The information has been verified (not a hypothesis or guess)
+- [ ] Future sessions will repeatedly need it (not one-time)
+- [ ] It won't become outdated quickly (not a temporary state)
+- [ ] No equivalent fact already exists in `.openclaw/facts/`
 
-- Use mneme for ALL task tracking
-- Always use `--json` flag for programmatic use
-- Check `mneme ready` before asking "what should I work on?"
-- Do NOT use `bd edit` (opens interactive editor)
-- Do NOT create markdown TODO lists for task tracking
-- Do NOT use external issue trackers
+All four must pass. Then propose and wait for human approval.
 
-<!-- END BEADS INTEGRATION -->
+## Task management reference
 
-## Landing the Plane (Session Completion)
+### Issue types
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+| Type | Use for |
+|---|---|
+| `bug` | Something broken |
+| `feature` | New functionality |
+| `task` | Work items: tests, docs, refactoring |
+| `epic` | Large feature with sub-tasks |
+| `chore` | Maintenance: dependencies, tooling |
 
-**MANDATORY WORKFLOW:**
+### Priorities
 
-1. **File issues for remaining work** - Create issues for anything that needs follow-up
-2. **Run quality gates** (if code changed) - Tests, linters, builds
-3. **Update issue status** - Close finished work, update in-progress items
-4. **PUSH TO REMOTE** - This is MANDATORY:
-   ```bash
-   git pull --rebase
-   git push
-   git status  # MUST show "up to date with origin"
-   ```
-5. **Clean up** - Clear stashes, prune remote branches
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
-
-**CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
-- NEVER stop before pushing - that leaves work stranded locally
-- NEVER say "ready to push when you are" - YOU must push
-- If push fails, resolve and retry until it succeeds
+| Priority | Level | Use for |
+|---|---|---|
+| `0` / P0 | Critical | Security, data loss, broken builds |
+| `1` / P1 | High | Major features, important bugs |
+| `2` / P2 | Medium | Default priority |
+| `3` / P3 | Low | Polish, optimization |
+| `4` / P4 | Backlog | Future ideas |
+
+### Commands
+
+```bash
+# Find work
+mneme ready                           # Unblocked tasks
+mneme list --status=open              # All open tasks
+mneme list --status=in_progress       # Active work
+mneme show <id>                       # Task details with dependencies
+mneme blocked                         # Tasks waiting on blockers
+
+# Create and link
+mneme create --title="..." --description="..." --type=task -p 2
+mneme dep add <child> <parent>
+
+# Update
+mneme update <id> --status=in_progress
+mneme update <id> --notes="Progress notes"
+
+# Complete
+mneme close <id> --reason="Done"
+```

package/src/templates/facts-architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-<!-- 在此记录项目的架构决策。示例：-->
-<!-- - 数据库使用 PostgreSQL，ORM 使用 SQLAlchemy -->
-<!-- - API 层使用 FastAPI，前端使用 React -->
-<!-- - 部署采用 Docker + K8s -->
+<!-- Record your project's architecture decisions here. Examples: -->
+<!-- - Database: PostgreSQL with pg (node-postgres) connection pool -->
+<!-- - API: Express 5 with JSON envelope responses -->
+<!-- - Deployment: Docker container behind nginx reverse proxy -->

package/src/templates/facts-invariants.md

@@ -1,6 +1,6 @@
-# Invariants — 不可违反的约束
+# Invariants
 
-<!-- 在此记录项目的硬性约束和红线。示例：-->
-<!-- - 所有 API 必须经过认证，禁止匿名访问 -->
-<!-- - 数据库 migration 必须向后兼容 -->
-<!-- - 响应时间不得超过 200ms (P99) -->
+<!-- Record hard constraints and rules that must never be violated. Examples: -->
+<!-- - All API endpoints require authentication (no anonymous access) -->
+<!-- - Database migrations must be backward-compatible -->
+<!-- - P99 response time must stay below 200ms -->

package/src/templates/facts-performance_rules.md

@@ -1,5 +1,5 @@
 # Performance Rules
 
-<!-- 在此记录性能相关的规则和约束。示例：-->
-<!-- - 批量操作优于逐条操作 -->
-<!-- - 缓存 TTL 不超过 5 分钟 -->
+<!-- Record performance-related rules and constraints. Examples: -->
+<!-- - Batch operations over bulk row-by-row inserts -->
+<!-- - Cache TTL must not exceed 5 minutes -->

package/src/templates/facts-pitfalls.md

@@ -1,5 +1,5 @@
-# Pitfalls — 已知陷阱
+# Pitfalls
 
-<!-- 在此记录踩过的坑和非显而易见的陷阱。示例：-->
-<!-- - MySQL 的 utf8 实际是 3 字节，需要用 utf8mb4 -->
-<!-- - Docker build 中 COPY 会导致缓存失效，注意顺序 -->
+<!-- Record non-obvious traps and lessons learned. Examples: -->
+<!-- - MySQL's utf8 is only 3 bytes; use utf8mb4 for full Unicode support -->
+<!-- - COPY in Dockerfile invalidates the build cache; order layers carefully -->

package/src/templates/opencode-prompt.md

@@ -1,48 +1,46 @@
-这是一个长期工程项目，请严格按以下顺序建立上下文：
+This is a long-running engineering project. Follow this sequence strictly at session start:
 
-## 第一步：读取 OpenClaw facts（长期事实）
+## Step 1: Read OpenClaw facts (long-term knowledge)
 
-请完整阅读以下文件：
+Read all of these files completely:
 - .openclaw/facts/architecture.md
 - .openclaw/facts/invariants.md
 - .openclaw/facts/performance_rules.md
 - .openclaw/facts/pitfalls.md
 
-这些内容是长期事实：
-- 优先级高于对话历史和你的推理
-- 不要随意推翻
-- 若发现矛盾，请提出而不是修改
+These are verified long-term facts:
+- They take priority over conversation history and your own reasoning
+- Do not override or dismiss them
+- If you find a contradiction, raise it instead of silently changing facts
 
-## 第二步：读取 Beads 当前任务列表
+## Step 2: Read current task state from Beads
 
-使用 `mneme` 命令查看当前任务状态：
-- `mneme ready` — 查看可执行任务（无阻塞依赖）
-- `mneme list --status=open` — 查看所有未完成任务
-- `mneme show <id>` — 查看具体任务详情
+Use `mneme` commands to check what work is available:
+- `mneme ready` — tasks with no blocking dependencies
+- `mneme list --status=open` — all incomplete tasks
+- `mneme show <id>` — details for a specific task
 
-## 第三步：选择 focus
+## Step 3: Pick a focus
 
-- 只选择一个 bead 作为本 session 的目标
-- 优先从 `mneme ready` 结果中选择
-- 选定后 claim 它：`mneme update <id> --status=in_progress`
-- 不要试图从对话历史中恢复状态
+- Choose exactly one task (bead) as this session's goal
+- Prefer tasks from `mneme ready` (no blockers)
+- Claim it: `mneme update <id> --status=in_progress`
+- Do not reconstruct progress from conversation history
 
-## 信息路由（自动执行，不需要用户指示）
+## Information routing (automatic — no user prompting needed)
 
-在工作过程中你会产生新信息。**你必须自动判断它属于哪一层**：
+As you work, you will discover new information. Classify it immediately:
 
-- **6 个月后还有用？** + 是事实/约束/教训 → **提议写入 OpenClaw**（需人工确认）
-- **6 个月后还有用？** + 是待办/进度 → **写入 Beads**（`mneme create` 或 `mneme update --notes`）
-- **下个 session 需要？** → **写入 Beads**
-- **仅当前操作需要？** → 留在 OpenCode，不持久化
+- **Long-term fact or constraint?** Propose to OpenClaw: `mneme propose --file=<name> --content="..." --reason="..."`
+- **Task or progress update?** Write to Beads: `mneme create` or `mneme update <id> --notes="..."`
+- **Only relevant right now?** Keep in context, do not persist
 
-写入 OpenClaw 前的检查：已验证 + 反复需要 + 不会快速过时 + 无重复。详见 AGENTS.md "三层路由决策" 一节。
+Before proposing a fact, verify: it's confirmed (not a guess), future sessions will need it, it won't become stale quickly, and no duplicate exists.
 
-## 重要原则
+## Key rules
 
-- 不要跳过上述步骤直接开始工作
-- 完成阶段性目标后更新 Beads：`mneme update <id> --notes="进度"`
-- 完成任务后关闭：`mneme close <id> --reason="完成说明"`
-- 发现新的长期事实时提议写入 OpenClaw（需人工确认）
-- Compaction 前必须持久化状态与结论
-- 禁止使用 `bd edit`（会打开交互式编辑器），使用 `mneme update` 代替
+- Do not skip these steps and jump straight to coding
+- After completing a milestone: `mneme update <id> --notes="what was done"`
+- After finishing a task: `mneme close <id> --reason="summary"`
+- Before compaction: persist all confirmed conclusions to Beads
+- Never use `bd edit` (opens interactive editor) — use `mneme update` with flags instead