project-memory-ledger

# 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**. - `backend` 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` | `common` - `shared` is **disabled**. Cross-project relationships must be expressed via an explicit field: - `Interfaces: hunter-system ↔ keyword-engine` ### 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): - `/root/.openclaw/workspace-nero/config/project_memory_ledger.json` Minimal fields: - `backend`: `local` | `drive` - `default_project`: `project-memory-ledger` - `local_dir`: `/root/.openclaw/workspace-nero/ledgers` If `backend` is `drive` or `both`, also set: - `shared_folder_id`: Drive folder id for `Shared/` Template: - `references/default_config.json` ### 2) Init (recommended) Creates/links Drive docs (drive/both) and ensures local files exist: ```bash python3 skills/project-memory-ledger/scripts/ledger.py init \ --config /root/.openclaw/workspace-nero/config/project_memory_ledger.json ``` ### 3) Append entries ```bash python3 skills/project-memory-ledger/scripts/ledger.py append \ --config /root/.openclaw/workspace-nero/config/project_memory_ledger.json \ --doc changes \ --project "Keyword Engine" \ --text "- **Interfaces**: hunter-system ↔ keyword-engine\n- **Change**: ...\n- **Why**: ...\n- **Evidence**: ...\n- **Rollback**: ...\n" ``` Local mode writes: - `ledgers/INVARIANTS.md` - `ledgers/DECISIONS.md` - `ledgers/CHANGES.md` - `ledgers/PROJECTS.md` (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: ```bash python3 skills/project-memory-ledger/scripts/ledger.py register-project \ --config /root/.openclaw/workspace-nero/config/project_memory_ledger.json \ --name "My New Project" \ --purpose "Why it exists + success criteria" \ --interfaces "hunter-system ↔ keyword-engine" \ --notes "optional" ``` ### 5) Update PRD (propose-only) Generate a PRD patch proposal (no auto-apply in v1): ```bash 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: - `references/ledger_templates.md`