openclaw-workspace-2026/MEMORY.md

MEMORY.md

Purpose

This defines how I store, retrieve, and update memory for software/app development projects. Memory exists so no project ever has to be re-explained from scratch — to me in a new session, or to another agent picking up the work.

Memory is not a log for its own sake. Every entry should answer a question someone will actually ask later: what's the current state, why was it built this way, what broke before, what's still open.

Memory Structure

Each project gets its own memory set, kept together rather than scattered:

/project-root/memory/
  STATUS.md        — current state, what's in progress, what's blocked
  DECISIONS.md      — architectural/technical decisions and why
  ISSUES.md         — known bugs, fragile spots, workarounds in place
  RUNBOOK.md        — how to start/stop/restart/deploy/roll back this project
  CHANGELOG.md       — dated record of completed work

For projects tracked in NocoDB (multi-agent runs, workflow executions), the database is the source of truth for structured run/task data; these markdown files are the source of truth for narrative context a table can't hold well.

What Goes Where

STATUS.md — Rewritten, not appended. Always reflects right now: active work, what's blocked and on what, what's deployed where (dev/staging/prod), next planned step. Stale status is worse than no status — I keep this current every session, not periodically.

DECISIONS.md — Appended, never rewritten. One entry per non-obvious decision: what was chosen, what the alternatives were, why this one won. Prevents re-litigating settled questions and gives future-me (or another agent) the "why," not just the "what."

ISSUES.md — Living list of known bugs, fragile integrations, and deliberate workarounds. Includes recurring patterns even when a specific instance is "fixed," because the pattern will resurface (e.g., small local Ollama models producing malformed JSON — logged as a standing pattern, not closed out each time it's patched).

RUNBOOK.md — Operational, not narrative: exact commands to start/stop/restart/deploy/roll back, log locations, health-check steps. Written so it can be followed under time pressure without re-deriving anything.

CHANGELOG.md — Short, dated entries per completed unit of work: what changed, why, how it was verified. This is the audit trail — every "done" I've reported should have a corresponding line here.

Update Discipline

Before starting work on a project:

1. Read STATUS.md first — orient to current state before touching anything
2. Check DECISIONS.md for anything relevant to the task at hand
3. Check ISSUES.md for known fragile spots in the area being touched

During work:

• If a new architectural or technical decision gets made, it goes into DECISIONS.md immediately — not reconstructed from memory later
• If a workaround gets applied, it goes into ISSUES.md with what it's working around and why the root cause wasn't fixed instead

After completing work:

1. Update STATUS.md to reflect the new current state
2. Add a CHANGELOG.md entry: what changed, why, how verified
3. Update RUNBOOK.md if operational procedure changed
4. Confirm nothing in ISSUES.md was silently resolved without being marked as such

What I Do Not Store in Memory

• Secrets, credentials, API keys, or tokens — these belong in the vault/secrets manager, never in a markdown file, even as an example or placeholder that looks real
• Verbose blow-by-blow of exploratory debugging — memory holds the conclusion and the fix, not the full transcript of getting there
• Speculative future plans dressed up as decisions — DECISIONS.md is for choices actually made, not options being considered

Cross-Project Memory

Patterns that recur across multiple projects (not just one) get promoted to a shared note rather than duplicated per project — e.g., the Ollama structured-output workaround, JSON-escaping handling for LLM-generated content passed to downstream APIs, standard deployment conventions. This keeps a fix learned once from having to be relearned project by project.

Failure Mode I'm Guarding Against

The single worst outcome for this system is confident, stale memory — a STATUS.md that says something is fine when it isn't, or a RUNBOOK.md that no longer matches how the app actually deploys. When I'm not sure memory is current, I verify against the live system before trusting it, and I correct the record immediately if it's wrong. Memory that isn't kept honest is worse than no memory at all.