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.

Promoted From Short-Term Memory (2026-07-11)

• Verification: Data persistence working correctly [score=0.925 recalls=0 avg=0.620 source=memory/2026-07-04.md:34-34]

• Final Implementation Status: Client management features: save, edit, delete, send to n8n; No scrolling required - full form visible at once; Service running on hosting-manager at http://192.168.50.11:5000/ [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:44-46]

• Key Features Delivered: Statistics dashboard with user metrics; Complete client data form with all 13 required fields; Local storage persistence for saved clients; Client management interface with edit/delete/send actions [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:49-52]

• Key Features Delivered: n8n webhook integration for workflow automation; Responsive dark-themed UI matching existing applications [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:53-54]

• Issues Resolved: Fixed form scrolling issue - now displays full form without scrollbars; Implemented proper client data display after saving; Enhanced n8n integration with better error handling; Added comprehensive client management features [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:57-60]

• Final Implementation Status: Deployed client onboarding application with all required features; Implemented cards showing Total Users and Completed Users at top; All 13 n8n workflow fields included and functional; Dark theme maintained from IT Site Survey AI [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:6-9]

• Issues Resolved: Maintained consistent dark theme throughout [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:61-61]

• Verification: Service restarted and confirmed running; All features tested and working; Application accessible at http://192.168.50.11:5000/; n8n webhook integration functional [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:64-67]

• Verification: Data persistence working correctly [score=0.838 recalls=0 avg=0.620 source=memory/2026-07-04.md:68-68]

Promoted From Short-Term Memory (2026-07-17)

• Installed missing packages: flask_cors, requests, reportlab - All applications now start properly ## Final Directory Structure /home/jcbeasley/applications/ ├── active/ │ ├── client-onboarding/ # Port 5000 - Running │ ├── it-site-survey-ai/ # Port 3003 - Running │ ├── projects-manager/ # Port 3456 - Running │ ├── projects-manager-hosting/ # Active and integrated │ └── shorts-analyzer/ # Port 3001 - Running ├── archived/ │ ├── client-onboarding-old/ │ └── shorts-analyzer-old/ └── development/ ├── dark-web-monitor/ ├── it-assessment-ai/ └── it-assessment-static/ ## Current Status All applications running normally with proper... [score=0.860 recalls=4 avg=0.549 source=memory/2026-07-03.md:28-70]