Establish baseline: core documentation and memory system
Adds foundational workspace documentation: - Core identity and operating principles (SOUL.md, IDENTITY.md, AGENTS.md, USER.md) - Memory management system specification (MEMORY.md) - Development team context and workflow (CONTEXT.md, PROJECTS.md) - Environment notes template (TOOLS.md) - Heartbeat task template (HEARTBEAT.md) Includes super-enhanced memory system: - JavaScript memory engine implementation - Memory initialization and test scripts - Daily memory logs for 2026-07-03, 2026-07-04 - Project-level memory structure for site-survey-ai Adds project templates: - Standard Python Flask application template
This commit is contained in:
@@ -0,0 +1,65 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user