Project Memory Ledger

Engineering project memory ledger with evidence + rollback (Invariants, Decision Log, Change Log). Use to extend conversations over time, reduce hallucinatio...

Security Scan

The skill's code, instructions, and requirements are consistent with a local-first project ledger that optionally scaffolds Drive documents; nothing requested or installed is disproportionate to that purpose.

Purpose & Capability

Name/description match what the files implement: a local Markdown ledger plus optional Drive scaffolding via the gws CLI. Declared required binary (python3) and recommended gws are appropriate for the stated features; no unrelated credentials or binaries are requested.

Instruction Scope

SKILL.md and README instruct reading a config file and writing local Markdown ledgers and, if chosen, invoking gws to create Drive folders/docs. The runtime instructions and the included script operate on the declared config paths and workspace files only; they do not attempt to read unrelated system credentials or post data to unexpected external endpoints. Note: default config examples point at /root paths which may be surprising for non-root setups.

Install Mechanism

No install spec and only an included Python script—no network downloads or external install steps in the skill bundle. Risk is limited to running the packaged script with python3 and optionally calling the gws CLI if Drive backend is used.

Credentials

The skill requires no environment variables or credentials in its metadata. Drive use requires the user to have gws authenticated or to provide Drive folder IDs in config; these are proportionate to the optional Drive features. There are no unexplained secret requests.

Persistence & Privilege

The skill is not always-enabled and is user-invocable. It writes files into workspace-configured directories and may create project folders; this is expected for a ledger and does not modify other skills or system-wide agent settings.

Assessment

This skill appears coherent with its description, but review a few things before installing/use: (1) run in local mode first (backend=local) to confirm where files are written and to avoid unintended Drive operations; (2) check and set the config paths (local_dir, projects_root_dir) to directories you control and avoid default /root locations if you are not running as root; (3) if you enable Drive backend, authenticate gws yourself and set the exact Drive folder IDs you want the skill to use (it will create folders/docs under those IDs); (4) inspect the included scripts (scripts/ledger.py) if you need to verify behavior—operations call gws via subprocess (no shell) and write local files, so run in a sandbox if you need extra assurance.

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