Project Memory Ledger

Maintain a durable, low-pollution ledger split into three books:

- Invariants: hard rules / stable facts
Decisions: tradeoffs and rationale
Changes: what changed + why + evidence + impact + rollback

Backends (configurable) — simplified semantics:

- The ledger is always local Markdown.
INLINECODE0 only controls where the project docs/assets are scaffolded and stored.

Values:

- local: create project directory structure locally and store docs as Markdown
drive: create Drive folder structure and store docs as GDoc/GSheet (requires gws auth)

Key conventions (write these into entries)

Project tagging (normalized, case-insensitive)

- Allowed Project slugs: hunter-system | keyword-engine | INLINECODE4
INLINECODE5 is disabled. Cross-project relationships must be expressed via an explicit field:

- INLINECODE6

Default project

If append is called without --project, the script injects:

- Project: project-memory-ledger (configurable by default_project)

Use this for improvements/bugs/requirements about this skill itself.

How to run

1) Configure (one-time)

Config path (recommended):

- INLINECODE11

Minimal fields:

- backend: local | INLINECODE14
INLINECODE15: INLINECODE16
INLINECODE17: INLINECODE18

If backend is drive or both, also set:

- shared_folder_id: Drive folder id for INLINECODE23

Template:

- INLINECODE24

2) Init (recommended)

Creates/links Drive docs (drive/both) and ensures local files exist: CODEBLOCK0

3) Append entries

CODEBLOCK1

Local mode writes:

- INLINECODE25
INLINECODE26
INLINECODE27
INLINECODE28 (when registering projects)

4) Register a project (project registry)

Use when something is worth upgrading into a maintained engineering project (creates a registry entry and records the decision). In drive/both, it also scaffolds a standard Drive folder structure by default: CODEBLOCK2

5) Update PRD (propose-only)

Generate a PRD patch proposal (no auto-apply in v1):

python3 skills/project-memory-ledger/scripts/ledger.py update-prd \
  --config /root/.openclaw/workspace-nero/config/project_memory_ledger.json \
  --project "Keyword Engine" \
  --mode propose

This writes to local ledgers/PRD_PATCHES.md (local/both) and prints the proposal.

Drive access note (optional)

Drive mode is a pluggable backend and is optional.

Drive backend options (not hard-bound)

- Option 1 (v1 implemented): gws CLI (must be installed + authenticated)
Option 2: Google API / service account (good for servers / CI)
Option 3: Third-party Drive tooling (user-chosen)

Recommended practice

If you don’t need humans editing the ledger, prefer local. If humans want to participate, keep the ledger local and have the agent generate Drive summaries (propose-only style).

What to record (assistant-owned scope)

- Drive structure changes (create/move/permissions)
systemd service/timer changes
SQLite schema/dedup logic changes (with before/after stats)
auth/publishing reliability fixes
output contract changes (doc/sheet rules)

Use templates:

- INLINECODE31

项目记忆账本

维护一个持久化、低污染的账本，分为三册：

- 不变项：硬性规则/稳定事实
决策项：权衡与依据
变更项：变更内容+原因+证据+影响+回滚方案

后端（可配置）——简化语义：

- 账本始终为本地Markdown格式。
backend仅控制项目文档/资产的搭建和存储位置。

取值：

- local：在本地创建项目目录结构，文档以Markdown格式存储
drive：创建云端硬盘文件夹结构，文档以GDoc/GSheet格式存储（需gws认证）

关键约定（写入条目时遵循）

项目标签（规范化，不区分大小写）

- 允许的Project标识：hunter-system | keyword-engine | common
shared已禁用。跨项目关系必须通过显式字段表达：

- Interfaces: hunter-system ↔ keyword-engine

默认项目

若调用append时未指定--project，脚本将自动注入：

- Project: project-memory-ledger（可通过default_project配置）

用于记录关于本技能本身的改进/缺陷/需求。

运行方式

1) 配置（一次性）

推荐配置路径：

- /root/.openclaw/workspace-nero/config/projectmemoryledger.json

必填字段：

- backend：local | drive
defaultproject：project-memory-ledger
localdir：/root/.openclaw/workspace-nero/ledgers

若backend为drive或both，还需设置：

- sharedfolderid：Shared/的云端硬盘文件夹ID

模板：

- references/default_config.json

2) 初始化（推荐）

创建/链接云端硬盘文档（drive/both模式）并确保本地文件存在： bash python3 skills/project-memory-ledger/scripts/ledger.py init \ --config /root/.openclaw/workspace-nero/config/projectmemoryledger.json

3) 追加条目

bash python3 skills/project-memory-ledger/scripts/ledger.py append \ --config /root/.openclaw/workspace-nero/config/projectmemoryledger.json \ --doc changes \ --project Keyword Engine \ --text - Interfaces: hunter-system ↔ keyword-engine\n- Change: ...\n- Why: ...\n- Evidence: ...\n- Rollback: ...\n

本地模式生成：

- ledgers/INVARIANTS.md
ledgers/DECISIONS.md
ledgers/CHANGES.md
ledgers/PROJECTS.md（注册项目时）

4) 注册项目（项目注册表）

当某个内容值得升级为受维护的工程项目时使用（创建注册条目并记录决策）。在drive/both模式下，默认还会搭建标准的云端硬盘文件夹结构： bash python3 skills/project-memory-ledger/scripts/ledger.py register-project \ --config /root/.openclaw/workspace-nero/config/projectmemoryledger.json \ --name My New Project \ --purpose Why it exists + success criteria \ --interfaces hunter-system ↔ keyword-engine \ --notes optional

5) 更新PRD（仅提案）

生成PRD补丁提案（v1版本不会自动应用）： bash python3 skills/project-memory-ledger/scripts/ledger.py update-prd \ --config /root/.openclaw/workspace-nero/config/projectmemoryledger.json \ --project Keyword Engine \ --mode propose

该命令将写入本地ledgers/PRD_PATCHES.md（local/both模式）并打印提案内容。

云端硬盘访问说明（可选）

云端硬盘模式是可插拔后端，为可选功能。

云端硬盘后端选项（非强制绑定）

- 选项1（v1已实现）：gws命令行工具（需安装并认证）
选项2：Google API/服务账号（适用于服务器/CI环境）
选项3：第三方云端硬盘工具（用户自选）

记录内容（助手负责范围）

- 云端硬盘结构变更（创建/移动/权限）
systemd服务/定时器变更
SQLite模式/去重逻辑变更（附前后统计）
认证/发布可靠性修复
输出契约变更（文档/表格规则）

使用模板：

- references/ledger_templates.md

project-memory-ledger项目记忆账本