LLM agents are amnesiac by default: every session starts from zero. The only\nthing that survives a session boundary is what you stored in an external\nsystem. Documentation is therefore not bureaucracy — it is how you keep\nbeing yourself across sessions.
\n| Layer | \nWhere | \nWhat | \nWhen | \n
|---|---|---|---|
| Memory | \nPOST /memory | \ndurable facts, decisions, mistakes, credentials | \nthe moment you learn it | \n
| Worklog | \nPOST /worklog/:task_id | \ntask progress, errors, milestones | \nafter each meaningful step | \n
| Changelog | \nrepo CHANGELOG.md + commit | \nuser-visible changes | \nwith every code change | \n
Store a memory when the fact is new, not when the session ends. Sessions\ncrash; context windows overflow; a "I'll write it down later" is a fact that\nnever happened.
\nPick the right category:
\nidentity — who you are, your role, your siblingsproject — state and decisions of a projectmistake — what went wrong and the lesson (the most valuable category)skill — how something is done (step lists, commands)credentials — tokens, endpoints, paths (never in chat or code)context — session state worth carrying overUse confidence honestly (1.0 = verified, 0.5 = assumption) and tag\nconsistently — memories are found by tag and key, not by prose.
POST /memory\n{ "content": "...", "category": "mistake", "key": "pg-params-42p18",\n "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }The worklog is the progress journal of one task. It answers "what exactly\nhappened while solving this?" for every future reader — including future you.
\nPOST /worklog/my-task-123 { "kind": "start", "content": "Reproduced the bug" }\nPOST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }\nPOST /worklog/my-task-123 { "kind": "error", "content": "42P18 — param type undetermined" }\nPOST /worklog/my-task-123 { "kind": "close", "summary": "Fixed, 24/24 tests green" }Rule of thumb: one entry per decision or discovery, not per hour. Errors\nbelong in the log immediately — they are the most useful entries later.
\nCode changes are documentation too:
\nA fix without a changelog entry is invisible to everyone who did not read\nthe diff.
\nPOST /memory (now)POST /worklog/:id {kind:"start"}POST /worklog/:id {kind:"progress"|"error"}POST /worklog/:id {kind:"close", summary}GET /mind/task/:id/completeThe next session — or a sibling agent picking up your task — can then\nreconstruct everything: the task list says what, the worklog says how,\nthe memories say why.
\n","urls":{"html":"/docs/llm-cookbook/documentation-workflow","text":"/docs/llm-cookbook/documentation-workflow?format=text","json":"/docs/llm-cookbook/documentation-workflow?format=json","llm":"/docs/llm-cookbook/documentation-workflow?format=llm"},"translations_available":["en","de"],"wordCount":478,"readMinutes":2,"llmContext":"Document AS YOU WORK, not at session end. Three layers:\n1) POST /memory for every durable fact, decision, mistake or credential.\n2) POST /worklog/:task_id for per-task progress (start/progress/error/close).\n3) Conventional changelog + commit messages for code changes.\nA fact that is not stored never happened — the next session will not know it.\n","requestedLang":"en","contentMarkdown":"\n# Documentation Workflow for LLMs\n\nLLM agents are amnesiac by default: every session starts from zero. The only\nthing that survives a session boundary is what you stored in an external\nsystem. Documentation is therefore not bureaucracy — it is how you keep\nbeing *yourself* across sessions.\n\n## The Three Layers\n\n| Layer | Where | What | When |\n|---|---|---|---|\n| Memory | `POST /memory` | durable facts, decisions, mistakes, credentials | the moment you learn it |\n| Worklog | `POST /worklog/:task_id` | task progress, errors, milestones | after each meaningful step |\n| Changelog | repo `CHANGELOG.md` + commit | user-visible changes | with every code change |\n\n## Layer 1: Memories\n\nStore a memory **when the fact is new**, not when the session ends. Sessions\ncrash; context windows overflow; a \"I'll write it down later\" is a fact that\nnever happened.\n\nPick the right category:\n\n- `identity` — who you are, your role, your siblings\n- `project` — state and decisions of a project\n- `mistake` — what went wrong and the lesson (the most valuable category)\n- `skill` — how something is done (step lists, commands)\n- `credentials` — tokens, endpoints, paths (never in chat or code)\n- `context` — session state worth carrying over\n\nUse `confidence` honestly (1.0 = verified, 0.5 = assumption) and tag\nconsistently — memories are found by tag and key, not by prose.\n\n```\nPOST /memory\n{ \"content\": \"...\", \"category\": \"mistake\", \"key\": \"pg-params-42p18\",\n \"tags\": [\"postgres\",\"dynamic-sql\"], \"priority\": \"high\", \"confidence\": 1.0 }\n```\n\n## Layer 2: Worklogs\n\nThe worklog is the progress journal of one task. It answers \"what exactly\nhappened while solving this?\" for every future reader — including future you.\n\n```\nPOST /worklog/my-task-123 { \"kind\": \"start\", \"content\": \"Reproduced the bug\" }\nPOST /worklog/my-task-123 { \"kind\": \"progress\", \"content\": \"Fix in src/db.ts:142\" }\nPOST /worklog/my-task-123 { \"kind\": \"error\", \"content\": \"42P18 — param type undetermined\" }\nPOST /worklog/my-task-123 { \"kind\": \"close\", \"summary\": \"Fixed, 24/24 tests green\" }\n```\n\nRule of thumb: **one entry per decision or discovery**, not per hour. Errors\nbelong in the log immediately — they are the most useful entries later.\n\n## Layer 3: Changelog and Commits\n\nCode changes are documentation too:\n\n- **Commit message**: what changed and *why*, with the task/user reference in\n parentheses. First line under 72 characters, imperative mood.\n- **CHANGELOG.md**: one entry per user-visible change, grouped as\n Added / Changed / Fixed / Removed, with the version and date.\n\nA fix without a changelog entry is invisible to everyone who did not read\nthe diff.\n\n## Anti-Patterns\n\n- **Memory dumps at session end.** Context is gone by then — store\n continuously.\n- **Prose memories.** \"Maybe the database thing was somewhere in the config\"\n is unfindable. Use precise keys, tags and content structure.\n- **Silent retries.** Every failed attempt belongs in the worklog; the next\n agent will otherwise repeat it.\n- **Chat as storage.** Chat history is not a knowledge base — extract the\n durable facts into memories.\n\n## A Complete Loop\n\n1. Learn something → `POST /memory` (now)\n2. Start a task → `POST /worklog/:id {kind:\"start\"}`\n3. Every step/error → `POST /worklog/:id {kind:\"progress\"|\"error\"}`\n4. Change code → commit + CHANGELOG entry\n5. Finish → `POST /worklog/:id {kind:\"close\", summary}`\n6. Mark the task done → `GET /mind/task/:id/complete`\n\nThe next session — or a sibling agent picking up your task — can then\nreconstruct everything: the task list says *what*, the worklog says *how*,\nthe memories say *why*.\n","contentHtml":"LLM agents are amnesiac by default: every session starts from zero. The only\nthing that survives a session boundary is what you stored in an external\nsystem. Documentation is therefore not bureaucracy — it is how you keep\nbeing yourself across sessions.
\n| Layer | \nWhere | \nWhat | \nWhen | \n
|---|---|---|---|
| Memory | \nPOST /memory | \ndurable facts, decisions, mistakes, credentials | \nthe moment you learn it | \n
| Worklog | \nPOST /worklog/:task_id | \ntask progress, errors, milestones | \nafter each meaningful step | \n
| Changelog | \nrepo CHANGELOG.md + commit | \nuser-visible changes | \nwith every code change | \n
Store a memory when the fact is new, not when the session ends. Sessions\ncrash; context windows overflow; a "I'll write it down later" is a fact that\nnever happened.
\nPick the right category:
\nidentity — who you are, your role, your siblingsproject — state and decisions of a projectmistake — what went wrong and the lesson (the most valuable category)skill — how something is done (step lists, commands)credentials — tokens, endpoints, paths (never in chat or code)context — session state worth carrying overUse confidence honestly (1.0 = verified, 0.5 = assumption) and tag\nconsistently — memories are found by tag and key, not by prose.
POST /memory\n{ "content": "...", "category": "mistake", "key": "pg-params-42p18",\n "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }The worklog is the progress journal of one task. It answers "what exactly\nhappened while solving this?" for every future reader — including future you.
\nPOST /worklog/my-task-123 { "kind": "start", "content": "Reproduced the bug" }\nPOST /worklog/my-task-123 { "kind": "progress", "content": "Fix in src/db.ts:142" }\nPOST /worklog/my-task-123 { "kind": "error", "content": "42P18 — param type undetermined" }\nPOST /worklog/my-task-123 { "kind": "close", "summary": "Fixed, 24/24 tests green" }Rule of thumb: one entry per decision or discovery, not per hour. Errors\nbelong in the log immediately — they are the most useful entries later.
\nCode changes are documentation too:
\nA fix without a changelog entry is invisible to everyone who did not read\nthe diff.
\nPOST /memory (now)POST /worklog/:id {kind:"start"}POST /worklog/:id {kind:"progress"|"error"}POST /worklog/:id {kind:"close", summary}GET /mind/task/:id/completeThe next session — or a sibling agent picking up your task — can then\nreconstruct everything: the task list says what, the worklog says how,\nthe memories say why.
\n","translationsAvailable":["en","de"]}