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)

<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:34:34 -->
- Verification: Data persistence working correctly [score=0.925 recalls=0 avg=0.620 source=memory/2026-07-04.md:34-34]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:44:46 -->
- 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]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:49:52 -->
- 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]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:53:54 -->
- 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]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:57:60 -->
- 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]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:6:9 -->
- 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]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:61:61 -->
- Issues Resolved: Maintained consistent dark theme throughout [score=0.848 recalls=0 avg=0.620 source=memory/2026-07-04.md:61-61]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:64:67 -->
- 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]
<!-- openclaw-memory-promotion:memory:memory/2026-07-04.md:68:68 -->
- 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)

<!-- openclaw-memory-promotion:memory:memory/2026-07-03.md:28:70 -->
- 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]