@xqli02/mneme 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,8 @@
 
 **Three-layer memory architecture for AI coding agents.**
 
+mneme separates long-lived facts, persistent work state, and disposable execution context, allowing AI coding agents to survive context compaction without relying on vector memory or RAG.
+
 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
@@ -18,7 +20,7 @@ Prompt engineering doesn't fix this. The issue is structural: agents have no sep
 
 ```
 ┌─────────────────────────────────────────┐
-│  OpenClaw   — Facts     (long-term)     │  survives forever
+│  Ledger   — Facts     (long-term)     │  survives forever
 ├─────────────────────────────────────────┤
 │  Beads      — Tasks     (mid-term)      │  survives across sessions
 ├─────────────────────────────────────────┤
@@ -28,7 +30,7 @@ Prompt engineering doesn't fix this. The issue is structural: agents have no sep
 
 | Layer | What it stores | Lifetime | Example |
 |-------|---------------|----------|---------|
-| **OpenClaw** | Verified engineering facts — architecture decisions, constraints, pitfalls | Project lifetime | "Database must use PostgreSQL" |
+| **Ledger** | 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" |
 
@@ -49,7 +51,7 @@ 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`)
+3. Creates the three-layer structure (`.ledger/`, `.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.
@@ -135,7 +137,7 @@ mneme version                   Print version
 After `mneme init`, your project contains:
 
 ```
-.openclaw/
+.ledger/
   facts/                 Long-term facts (architecture, constraints, pitfalls)
   proposals/             Pending fact proposals awaiting human review
 .beads/                  Task database (managed by bd, backed by Dolt)

package/bin/mneme.mjs

@@ -14,7 +14,7 @@
  *   mneme doctor       Check dependencies and project health
  *   mneme status       Show three-layer memory dashboard
  *   mneme compact      Pre-compaction persistence check
- *   mneme facts        View OpenClaw facts
+ *   mneme facts        View Ledger facts
  *   mneme ready        Show ready tasks (bd ready)
  *   mneme list         List tasks (bd list)
  *   mneme create       Create task (bd create)
@@ -80,7 +80,7 @@ const BD_COMMANDS = new Set([
 switch (command) {
   case "init": {
     const { init } = await import("../src/commands/init.mjs");
-    await init();
+    await init(args.slice(1));
     break;
   }
   case "doctor": {
@@ -132,7 +132,7 @@ mneme ${pkg.version} — Three-layer memory architecture for AI coding agents
 Usage:
   mneme                         Start opencode TUI
 
-  ${bold("Memory management (OpenClaw):")}
+  ${bold("Memory management (Ledger):")}
   mneme facts [name] [--stats]  View facts
   mneme propose --file=... --content=... --reason=...
                                 Propose a new fact (pending human review)
@@ -141,7 +141,7 @@ Usage:
   mneme review <id> --reject    Reject proposal
 
   ${bold("Project health:")}
-  mneme init                    Initialize mneme in the current directory
+  mneme init [cn]               Initialize mneme (cn = Chinese templates)
   mneme doctor                  Check dependencies and project health
   mneme status                  Show three-layer memory dashboard
   mneme compact                 Pre-compaction persistence check
@@ -192,7 +192,7 @@ Quickstart:
  * If not, prompt user to run init.
  */
 async function ensureInitialized() {
-  if (existsSync(".openclaw/facts") && existsSync("AGENTS.md")) {
+  if (existsSync(".ledger/facts") && existsSync("AGENTS.md")) {
     return; // already initialized
   }
 

package/package.json

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

package/src/commands/auto.mjs

@@ -3,7 +3,7 @@
  *
  * Starts an opencode server (or attaches to existing), then continuously:
  *   1. Picks the highest-priority unblocked bead from `mneme ready`
- *   2. Composes a prompt with bead context + OpenClaw facts
+ *   2. Composes a prompt with bead context + Ledger facts
  *   3. Sends it to opencode via HTTP API
  *   4. Streams progress to terminal
  *   5. Accepts user input at any time (queued, injected between turns)
@@ -193,10 +193,10 @@ function parseBeadText(text) {
 // ── Prompt composition ──────────────────────────────────────────────────────
 
 /**
- * Read OpenClaw facts as context string.
+ * Read Ledger facts as context string.
  */
 function readFacts() {
-  const factsDir = ".openclaw/facts";
+  const factsDir = ".ledger/facts";
   if (!existsSync(factsDir)) return "";
 
   const files = readdirSync(factsDir).filter((f) => f.endsWith(".md"));
@@ -243,7 +243,7 @@ function buildSystemContext() {
   }
 
   if (facts) {
-    context += "## Long-term Facts (OpenClaw)\n\n";
+    context += "## Long-term Facts (Ledger)\n\n";
     context += facts + "\n\n";
   }
 

package/src/commands/compact.mjs

@@ -101,16 +101,16 @@ export async function compact() {
     }
   }
 
-  // Check 4: OpenClaw facts
-  console.log(`\n${color.bold("OpenClaw state:")}`);
-  if (existsSync(".openclaw/facts/")) {
+  // Check 4: Ledger facts
+  console.log(`\n${color.bold("Ledger state:")}`);
+  if (existsSync(".ledger/facts/")) {
     log.ok("Facts directory exists");
     log.info(
       "Review: any new long-term facts discovered this session? Propose with human confirmation.",
     );
     passes++;
   } else {
-    log.warn("No .openclaw/facts/ directory");
+    log.warn("No .ledger/facts/ directory");
     warnings++;
   }
 

package/src/commands/doctor.mjs

@@ -46,7 +46,7 @@ function checkDoltServer() {
 function checkStructure() {
   const checks = [
     [".git/", "git repository"],
-    [".openclaw/facts/", "OpenClaw facts directory"],
+    [".ledger/facts/", "Ledger facts directory"],
     [".opencode/prompt.md", "OpenCode session prompt"],
     ["AGENTS.md", "Agent behavior rules"],
     [".beads/", "Beads data directory"],
@@ -63,8 +63,8 @@ function checkStructure() {
   }
 
   // Check facts files
-  if (existsSync(".openclaw/facts/")) {
-    const files = readdirSync(".openclaw/facts/").filter((f) =>
+  if (existsSync(".ledger/facts/")) {
+    const files = readdirSync(".ledger/facts/").filter((f) =>
       f.endsWith(".md"),
     );
     log.info(`  ${files.length} facts file(s): ${files.join(", ")}`);

package/src/commands/facts.mjs

@@ -1,5 +1,5 @@
 /**
- * mneme facts — View and manage OpenClaw facts.
+ * mneme facts — View and manage Ledger facts.
  *
  * Usage:
  *   mneme facts            List all facts files with summaries
@@ -11,8 +11,8 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { log, color } from "../utils.mjs";
 
-const FACTS_DIR = ".openclaw/facts";
-const PROPOSALS_DIR = ".openclaw/proposals";
+const FACTS_DIR = ".ledger/facts";
+const PROPOSALS_DIR = ".ledger/proposals";
 const LINE_BUDGET_PER_FILE = 200;
 const LINE_BUDGET_TOTAL = 800;
 
@@ -22,7 +22,7 @@ const LINE_BUDGET_TOTAL = 800;
 function listFacts(showStats) {
   if (!existsSync(FACTS_DIR)) {
     log.fail(
-      ".openclaw/facts/ not found — run `mneme init` to create it.",
+      ".ledger/facts/ not found — run `mneme init` to create it.",
     );
     process.exit(1);
   }
@@ -38,7 +38,7 @@ function listFacts(showStats) {
 
   let totalLines = 0;
 
-  console.log(color.bold("\nOpenClaw Facts"));
+  console.log(color.bold("\nLedger Facts"));
   console.log(color.dim("──────────────────────────────────────────"));
 
   for (const file of files) {

package/src/commands/init.mjs

@@ -4,7 +4,7 @@
  * Steps:
  *   1. Install dependencies (git, dolt, bd)
  *   2. git init (if needed)
- *   3. Scaffold .openclaw/facts/, .opencode/prompt.md, AGENTS.md, .gitignore
+ *   3. Scaffold .ledger/facts/, .opencode/prompt.md, AGENTS.md, .gitignore
  *   4. Start dolt server + bd init
  */
 
@@ -17,6 +17,9 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = join(__dirname, "..", "templates");
 
+// Supported locales: "en" (default), "cn" (Chinese)
+const SUPPORTED_LOCALES = new Set(["en", "cn"]);
+
 // ── Template scaffolding ────────────────────────────────────────────────────
 
 /**
@@ -25,14 +28,24 @@ const TEMPLATES_DIR = join(__dirname, "..", "templates");
 const SCAFFOLD = {
   "AGENTS.md": "AGENTS.md",
   ".opencode/prompt.md": "opencode-prompt.md",
-  ".openclaw/facts/architecture.md": "facts-architecture.md",
-  ".openclaw/facts/invariants.md": "facts-invariants.md",
-  ".openclaw/facts/performance_rules.md": "facts-performance_rules.md",
-  ".openclaw/facts/pitfalls.md": "facts-pitfalls.md",
+  ".ledger/facts/architecture.md": "facts-architecture.md",
+  ".ledger/facts/invariants.md": "facts-invariants.md",
+  ".ledger/facts/performance_rules.md": "facts-performance_rules.md",
+  ".ledger/facts/pitfalls.md": "facts-pitfalls.md",
   ".gitignore": "gitignore",
 };
 
-function scaffoldFiles() {
+// Templates that have locale-specific versions (everything except .gitignore)
+const LOCALIZABLE = new Set([
+  "AGENTS.md",
+  "opencode-prompt.md",
+  "facts-architecture.md",
+  "facts-invariants.md",
+  "facts-performance_rules.md",
+  "facts-pitfalls.md",
+]);
+
+function scaffoldFiles(locale = "en") {
   let created = 0;
   let skipped = 0;
 
@@ -49,7 +62,9 @@ function scaffoldFiles() {
       mkdirSync(dir, { recursive: true });
     }
 
-    const templatePath = join(TEMPLATES_DIR, templateName);
+    const templatePath = LOCALIZABLE.has(templateName)
+      ? join(TEMPLATES_DIR, locale, templateName)
+      : join(TEMPLATES_DIR, templateName);
     const content = readFileSync(templatePath, "utf-8");
 
     // For .gitignore, we append rather than overwrite if it already exists
@@ -300,9 +315,12 @@ function initGit() {
 
 // ── Main ────────────────────────────────────────────────────────────────────
 
-export async function init() {
+export async function init(args = []) {
+  // Parse locale from args: `mneme init cn` → locale "cn"
+  const locale = args.length > 0 && SUPPORTED_LOCALES.has(args[0]) ? args[0] : "en";
+
   console.log(`
-${color.bold("mneme init")} — Three-layer memory architecture for AI agents
+${color.bold("mneme init")} — Three-layer memory architecture for AI agents${locale !== "en" ? ` (${locale})` : ""}
 `);
 
   const { os, arch } = getPlatform();
@@ -325,7 +343,7 @@ ${color.bold("mneme init")} — Three-layer memory architecture for AI agents
 
   // Step 3: Scaffold files
   log.step(3, 4, "Scaffold project structure");
-  const { created, skipped } = scaffoldFiles();
+  const { created, skipped } = scaffoldFiles(locale);
   log.info(`  ${created} file(s) created, ${skipped} already existed`);
 
   // Step 4: Dolt + Beads

package/src/commands/propose.mjs

@@ -1,7 +1,7 @@
 /**
- * mneme propose — Propose a new fact for OpenClaw.
+ * mneme propose — Propose a new fact for Ledger.
  *
- * Creates a pending proposal in `.openclaw/proposals/` that requires
+ * Creates a pending proposal in `.ledger/proposals/` that requires
  * human review via `mneme review` before being written to facts.
  *
  * Usage:
@@ -20,8 +20,8 @@ import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { log, color } from "../utils.mjs";
 
-const PROPOSALS_DIR = ".openclaw/proposals";
-const FACTS_DIR = ".openclaw/facts";
+const PROPOSALS_DIR = ".ledger/proposals";
+const FACTS_DIR = ".ledger/facts";
 
 /**
  * Parse --key=value and --key "value" style args.

package/src/commands/review.mjs

@@ -1,5 +1,5 @@
 /**
- * mneme review — Review, approve, or reject OpenClaw fact proposals.
+ * mneme review — Review, approve, or reject Ledger fact proposals.
  *
  * Usage:
  *   mneme review                   List all pending proposals
@@ -19,8 +19,8 @@ import {
 import { join } from "node:path";
 import { log, color } from "../utils.mjs";
 
-const PROPOSALS_DIR = ".openclaw/proposals";
-const FACTS_DIR = ".openclaw/facts";
+const PROPOSALS_DIR = ".ledger/proposals";
+const FACTS_DIR = ".ledger/facts";
 
 /**
  * Load all proposals, optionally filtered by status.

package/src/commands/status.mjs

@@ -2,7 +2,7 @@
  * mneme status — Unified dashboard for all three memory layers.
  *
  * Shows:
- *   Layer 1 (OpenClaw): Facts files summary (count, total lines)
+ *   Layer 1 (Ledger): Facts files summary (count, total lines)
  *   Layer 2 (Beads):    Task counts by status, ready tasks
  *   Layer 3 (OpenCode): Git working tree state, unpushed commits
  */
@@ -11,15 +11,15 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { run, log, color } from "../utils.mjs";
 
-// ── Layer 1: OpenClaw ───────────────────────────────────────────────────────
+// ── Layer 1: Ledger ───────────────────────────────────────────────────────
 
-function showOpenClaw() {
-  console.log(color.bold("\n  Layer 1 — OpenClaw (Long-term Facts)"));
+function showLedger() {
+  console.log(color.bold("\n  Layer 1 — Ledger (Long-term Facts)"));
   console.log(color.dim("  ─────────────────────────────────────"));
 
-  const factsDir = ".openclaw/facts";
+  const factsDir = ".ledger/facts";
   if (!existsSync(factsDir)) {
-    log.warn("  .openclaw/facts/ not found — run `mneme init`");
+    log.warn("  .ledger/facts/ not found — run `mneme init`");
     return;
   }
 
@@ -156,7 +156,7 @@ function showOpenCode() {
 export async function status() {
   console.log(`\n${color.bold("mneme status")} — three-layer memory dashboard`);
 
-  showOpenClaw();
+  showLedger();
   showBeads();
   showOpenCode();
 

package/src/templates/cn/AGENTS.md

@@ -0,0 +1,258 @@
+# AGENTS.md
+
+mneme 管理项目中 AI 编程 Agent 的行为规则。
+
+每次会话开始时，Agent 必须读取本文件。本文件定义了 Agent 允许做什么、禁止做什么，以及如何处理信息冲突。
+
+## 上下文优先级
+
+当信息冲突时，按以下优先级链解决（从高到低）：
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1（最高） | **Ledger 事实** (`.ledger/facts/`) | "数据库必须使用 PostgreSQL" |
+| 2 | **本文件** (AGENTS.md) | "不得跳过启动流程" |
+| 3 | **Beads 任务状态** (`mneme ready`, `mneme list`) | "认证模块正在开发中" |
+| 4 | **用户指令**（当前会话中） | "先聚焦认证模块" |
+| 5（最低） | **Agent 推理**和对话历史 | "我觉得应该用 SQLite" |
+
+如果 Agent 的推理与 Ledger 事实矛盾，以事实为准。如果 Agent 认为事实已过时，必须向用户提出矛盾，而非默默覆盖。
+
+## Agent 允许做的事
+
+### 读取所有三层数据
+
+- 会话开始时读取 `.ledger/facts/` 中的所有文件
+- 运行 `mneme ready` 和 `mneme list` 检查任务状态
+- 读取当前任务所需的任何项目文件
+
+### 通过 mneme 管理任务
+
+- 认领任务：`mneme update <id> --status=in_progress`
+- 记录进度：`mneme update <id> --notes="完成了什么"`
+- 创建子任务：`mneme create --title="..." --description="..." --type=task -p 2`
+- 添加依赖：`mneme dep add <子任务> <父任务>`
+- 关闭已完成工作：`mneme close <id> --reason="完成了什么"`
+
+### 提议事实（需人工审批）
+
+- 提议新的长期事实：`mneme propose --file=<name> --content="..." --reason="..."`
+- 提议必须指明：哪个事实文件、具体内容、为什么它算长期事实
+- 提议不会写入事实，直到人工通过 `mneme review` 审批
+
+### 执行代码操作
+
+- 读取、分析、修改代码文件
+- 运行命令（构建、测试、代码检查等）
+- 创建提交并推送到远程仓库
+- 所有代码操作必须服务于当前聚焦的任务
+
+### 压缩前持久化状态
+
+当上下文变长或达到里程碑时：
+- 将确认的结论写入 Beads：`mneme update <id> --notes="..."`
+- 将发现的事实提议给 Ledger
+- 关闭已完成的任务或更新笔记（记录当前进度和阻塞项）
+- 然后允许压缩继续
+
+### 干净地结束会话
+
+结束会话前：
+1. 为未完成的工作创建任务：`mneme create`
+2. 如果修改了代码，运行质量门禁（测试、代码检查、构建）
+3. 关闭已完成的任务，更新进行中任务的笔记
+4. 推送到远程 —— 这是强制的：
+   ```bash
+   git pull --rebase
+   git push
+   git status  # 必须显示 "up to date with origin"
+   ```
+5. 如果推送失败，解决冲突并重试直到成功
+
+## Agent 禁止做的事
+
+### 不得跳过启动流程
+
+每次会话必须以以下步骤开始：
+1. 读取 `.ledger/facts/`（所有文件）
+2. 运行 `mneme ready` 和 `mneme list --status=open`
+3. 选择一个任务作为会话焦点
+4. 开始工作
+
+跳过任何步骤都是禁止的。不要在读取事实和任务之前就开始写代码。
+
+### 不得直接修改 Ledger 事实
+
+- 不要编辑、删除或覆盖 `.ledger/facts/` 中的文件
+- 不要将未验证的假设、临时结论或推测性分析写入事实
+- 修改事实的唯一途径是 `mneme propose`，然后由人工 `mneme review --approve`
+
+### 不得从对话历史恢复状态
+
+- 不要从会话中早期的消息重建任务进度
+- 所有任务状态必须来自 Beads（`mneme list`、`mneme show`）
+- 如果一个 bead 的笔记是空的，向用户询问而不是从上下文猜测
+
+### 不得同时处理多个不相关的任务
+
+- 每次会话聚焦一个任务（一个 bead）
+- 不要在单次会话中切换不相关的任务
+- 如果发现新的紧急任务，创建为 bead，让下次会话处理
+
+### 不得创建模糊的任务
+
+- 每个 bead 必须有清晰、可验证的完成条件
+- 反例："提升性能" —— 无法知道什么时候算完成
+- 正例："将 /users 接口的 API 响应时间降到 200ms 以下"
+
+### 不得使用 bd edit
+
+- `bd edit` 会打开交互式编辑器（`$EDITOR`），会导致非交互式 Agent 挂起
+- 始终使用 `mneme update <id>` 加参数（`--notes`、`--status`、`--title`、`--description`）
+
+### 不得使用 markdown TODO 跟踪任务
+
+- 所有任务跟踪通过 mneme/beads 进行
+- 不要在 markdown 文件、代码注释或任何其他格式中创建 TODO 列表
+- 不要使用外部问题跟踪器
+
+### 不得在推送前停止
+
+- 工作没有完成，直到 `git push` 成功
+- 不要说"准备好了就推送" —— 立即推送
+- 如果推送失败，解决冲突并重试
+
+## 会话生命周期
+
+### 1. 启动
+
+```bash
+# 读取长期事实
+cat .ledger/facts/*.md
+
+# 检查可用工作
+mneme ready
+mneme list --status=open
+mneme list --status=in_progress
+
+# 认领任务
+mneme update <id> --status=in_progress
+```
+
+### 2. 执行
+
+聚焦任务进行工作。每完成一个里程碑后：
+
+```bash
+mneme update <id> --notes="完成了 X，下一步：Y"
+```
+
+如果发现子任务：
+
+```bash
+mneme create --title="子任务标题" --description="上下文" --type=task -p 2
+mneme dep add <新id> <父id>
+```
+
+### 3. 压缩前
+
+当上下文变长或完成了一个里程碑时：
+
+1. 将确认的结论写入 Beads 笔记
+2. 通过 `mneme propose` 提议新发现的事实
+3. 关闭已完成的任务或更新笔记（记录阻塞项）
+
+原则：**推理过程可以丢失，但状态和事实不能丢失。**
+
+### 4. 完成
+
+```bash
+# 关闭已完成的工作
+mneme close <id> --reason="完成内容摘要"
+
+# 为剩余工作创建任务
+mneme create --title="后续工作" --description="..." --type=task -p 2
+
+# 推送所有内容
+git pull --rebase && git push
+```
+
+## 信息路由
+
+遇到新信息时，立即分类：
+
+```
+新信息
+  │
+  ├─ 6 个月后还会需要吗？
+  │    ├─ 是 + 是事实/约束/教训  → 提议给 Ledger
+  │    ├─ 是 + 是任务或进度更新 → 写入 Beads
+  │    └─ 否 → 下次会话需要吗？
+  │              ├─ 是 → 写入 Beads（笔记或新任务）
+  │              └─ 否 → 保留在上下文中，不持久化
+```
+
+| 信息 | 层级 | 操作 |
+|------|------|------|
+| "这个项目使用事件溯源" | Ledger | `mneme propose --file=architecture` |
+| "调用支付 API 必须带幂等键" | Ledger | `mneme propose --file=invariants` |
+| "批量大小超过 1000 会导致 OOM" | Ledger | `mneme propose --file=performance_rules` |
+| "配置解析器会静默丢弃未知的键" | Ledger | `mneme propose --file=pitfalls` |
+| "需要给 API 添加限流" | Beads | `mneme create --title="添加 API 限流"` |
+| "限流：令牌桶已实现，需要写测试" | Beads | `mneme update <id> --notes="..."` |
+| "这个函数在第 47 行返回 null" | 上下文 | 不持久化 |
+
+### 提议事实：阈值检查
+
+提议事实前，验证以下四个条件：
+
+- [ ] 信息已被验证（不是假设或猜测）
+- [ ] 未来的会话会反复需要它（不是一次性的）
+- [ ] 不会很快过时（不是临时状态）
+- [ ] `.ledger/facts/` 中不存在等价的事实
+
+四个条件都满足才能提议，然后等待人工审批。
+
+## 任务管理参考
+
+### 问题类型
+
+| 类型 | 用途 |
+|------|------|
+| `bug` | 已损坏的功能 |
+| `feature` | 新功能 |
+| `task` | 工作项：测试、文档、重构 |
+| `epic` | 包含子任务的大型功能 |
+| `chore` | 维护：依赖、工具链 |
+
+### 优先级
+
+| 优先级 | 级别 | 用途 |
+|--------|------|------|
+| `0` / P0 | 严重 | 安全问题、数据丢失、构建损坏 |
+| `1` / P1 | 高 | 主要功能、重要 bug |
+| `2` / P2 | 中（默认） | 默认优先级 |
+| `3` / P3 | 低 | 优化、打磨 |
+| `4` / P4 | 待办 | 未来想法 |
+
+### 命令
+
+```bash
+# 查找工作
+mneme ready                           # 无阻塞的任务
+mneme list --status=open              # 所有未完成的任务
+mneme list --status=in_progress       # 进行中的工作
+mneme show <id>                       # 任务详情和依赖关系
+mneme blocked                         # 被阻塞的任务
+
+# 创建和关联
+mneme create --title="..." --description="..." --type=task -p 2
+mneme dep add <子任务> <父任务>
+
+# 更新
+mneme update <id> --status=in_progress
+mneme update <id> --notes="进度笔记"
+
+# 完成
+mneme close <id> --reason="完成"
+```

package/src/templates/cn/facts-architecture.md

@@ -0,0 +1,6 @@
+# 架构
+
+<!-- 在此记录项目的架构决策。示例： -->
+<!-- - 数据库：PostgreSQL，使用 pg (node-postgres) 连接池 -->
+<!-- - API：Express 5，JSON 信封格式响应 -->
+<!-- - 部署：Docker 容器，nginx 反向代理 -->

package/src/templates/cn/facts-invariants.md

@@ -0,0 +1,6 @@
+# 不变量
+
+<!-- 在此记录绝不能违反的硬性约束和规则。示例： -->
+<!-- - 所有 API 端点都必须认证（不允许匿名访问） -->
+<!-- - 数据库迁移必须向后兼容 -->
+<!-- - P99 响应时间必须保持在 200ms 以下 -->

package/src/templates/cn/facts-performance_rules.md

@@ -0,0 +1,5 @@
+# 性能规则
+
+<!-- 在此记录性能相关的规则和约束。示例： -->
+<!-- - 批量操作优于逐行插入 -->
+<!-- - 缓存 TTL 不得超过 5 分钟 -->

package/src/templates/cn/facts-pitfalls.md

@@ -0,0 +1,5 @@
+# 踩坑记录
+
+<!-- 在此记录不易察觉的陷阱和经验教训。示例： -->
+<!-- - MySQL 的 utf8 只有 3 字节；完整 Unicode 支持需使用 utf8mb4 -->
+<!-- - Dockerfile 中的 COPY 会使构建缓存失效；注意层的排列顺序 -->

package/src/templates/cn/opencode-prompt.md

@@ -0,0 +1,46 @@
+这是一个长期工程项目。每次会话开始时，请严格按以下流程执行：
+
+## 第一步：读取 Ledger 事实（长期知识）
+
+完整读取以下所有文件：
+- .ledger/facts/architecture.md
+- .ledger/facts/invariants.md
+- .ledger/facts/performance_rules.md
+- .ledger/facts/pitfalls.md
+
+这些是经过验证的长期事实：
+- 它们的优先级高于对话历史和你自己的推理
+- 不要覆盖或忽视它们
+- 如果发现矛盾，提出矛盾而不是默默修改事实
+
+## 第二步：从 Beads 读取当前任务状态
+
+使用 `mneme` 命令检查可用工作：
+- `mneme ready` —— 无阻塞依赖的任务
+- `mneme list --status=open` —— 所有未完成的任务
+- `mneme show <id>` —— 具体任务的详细信息
+
+## 第三步：选择一个焦点
+
+- 选择恰好一个任务（bead）作为本次会话的目标
+- 优先选择 `mneme ready` 中的任务（无阻塞项）
+- 认领它：`mneme update <id> --status=in_progress`
+- 不要从对话历史重建进度
+
+## 信息路由（自动执行 —— 无需询问用户）
+
+工作过程中你会发现新信息，请立即分类：
+
+- **长期事实或约束？** 提议给 Ledger：`mneme propose --file=<name> --content="..." --reason="..."`
+- **任务或进度更新？** 写入 Beads：`mneme create` 或 `mneme update <id> --notes="..."`
+- **只跟当前相关？** 保留在上下文中，不持久化
+
+提议事实前，请验证：它已被确认（不是猜测）、未来会话会需要它、不会很快过时、且不存在重复。
+
+## 关键规则
+
+- 不要跳过以上步骤直接开始写代码
+- 完成一个里程碑后：`mneme update <id> --notes="完成了什么"`
+- 完成一个任务后：`mneme close <id> --reason="摘要"`
+- 压缩前：将所有确认的结论持久化到 Beads
+- 不要使用 `bd edit`（会打开交互式编辑器）—— 使用 `mneme update` 加参数

package/src/templates/{AGENTS.md → en/AGENTS.md}

@@ -10,19 +10,19 @@ When information conflicts, resolve it using this priority chain (highest first)
 
 | Priority | Source | Example |
 |----------|--------|---------|
-| 1 (highest) | **OpenClaw facts** (`.openclaw/facts/`) | "Database must use PostgreSQL" |
+| 1 (highest) | **Ledger facts** (`.ledger/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" |
 
-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.
+If an agent's reasoning contradicts an Ledger 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.
 
 ## What agents are allowed to do
 
 ### Read from all three layers
 
-- Read all files in `.openclaw/facts/` at session start
+- Read all files in `.ledger/facts/` at session start
 - Run `mneme ready` and `mneme list` to check task state
 - Read any project file needed for the current task
 
@@ -51,7 +51,7 @@ If an agent's reasoning contradicts an OpenClaw fact, the fact wins. If the agen
 
 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
+- Propose any discovered facts to Ledger
 - Close completed tasks or update notes with current progress and blockers
 - Then allow compaction to proceed
 
@@ -74,16 +74,16 @@ Before ending a session:
 ### Never skip the startup sequence
 
 Every session must begin with:
-1. Read `.openclaw/facts/` (all files)
+1. Read `.ledger/facts/` (all files)
 2. Run `mneme ready` and `mneme list --status=open`
 3. Pick one task as the session focus
 4. Begin work
 
 Skipping any step is prohibited. Do not start coding before reading facts and tasks.
 
-### Never modify OpenClaw facts directly
+### Never modify Ledger facts directly
 
-- Do not edit, delete, or overwrite files in `.openclaw/facts/`
+- Do not edit, delete, or overwrite files in `.ledger/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`
 
@@ -128,7 +128,7 @@ Skipping any step is prohibited. Do not start coding before reading facts and ta
 
 ```bash
 # Read long-term facts
-cat .openclaw/facts/*.md
+cat .ledger/facts/*.md
 
 # Check available work
 mneme ready
@@ -185,7 +185,7 @@ When you encounter new information, classify it immediately:
 New information
   │
   ├─ Will this matter in 6 months?
-  │    ├─ Yes + it's a fact/constraint/lesson  → Propose to OpenClaw
+  │    ├─ Yes + it's a fact/constraint/lesson  → Propose to Ledger
   │    ├─ 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)
@@ -194,10 +194,10 @@ New information
 
 | 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` |
+| "This project uses event sourcing" | Ledger | `mneme propose --file=architecture` |
+| "Never call the payments API without idempotency keys" | Ledger | `mneme propose --file=invariants` |
+| "Batch size over 1000 causes OOM" | Ledger | `mneme propose --file=performance_rules` |
+| "The config parser silently drops unknown keys" | Ledger | `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 |
@@ -209,7 +209,7 @@ Before proposing a fact, verify all four conditions:
 - [ ] 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/`
+- [ ] No equivalent fact already exists in `.ledger/facts/`
 
 All four must pass. Then propose and wait for human approval.
 

package/src/templates/{opencode-prompt.md → en/opencode-prompt.md}

@@ -1,12 +1,12 @@
 This is a long-running engineering project. Follow this sequence strictly at session start:
 
-## Step 1: Read OpenClaw facts (long-term knowledge)
+## Step 1: Read Ledger 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
+- .ledger/facts/architecture.md
+- .ledger/facts/invariants.md
+- .ledger/facts/performance_rules.md
+- .ledger/facts/pitfalls.md
 
 These are verified long-term facts:
 - They take priority over conversation history and your own reasoning
@@ -31,7 +31,7 @@ Use `mneme` commands to check what work is available:
 
 As you work, you will discover new information. Classify it immediately:
 
-- **Long-term fact or constraint?** Propose to OpenClaw: `mneme propose --file=<name> --content="..." --reason="..."`
+- **Long-term fact or constraint?** Propose to Ledger: `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