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:

python3 skills/project-memory-ledger/scripts/ledger.py init \
  --config /root/.openclaw/workspace-nero/config/project_memory_ledger.json

3) Append entries

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:

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):

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