Workspace Memory System and Internal Decision Records
Overview
workspace/*.md is the repository’s persistent engineering-memory layer. It keeps the repo map, changelog, decisions, patterns, debugging notes, TODOs, and tone/behavior guidance close to the code so future sessions can recover context quickly without rescanning the full repository.
This layer is intentionally narrower than product or operational documentation. It captures structural knowledge, durable conventions, trade-offs, incidents, and next actions; it does not replace feature docs, deployment notes, API contracts, or runbooks maintained elsewhere in the repository.
Architecture Overview
flowchart TB
Code[Repository changes and context]
subgraph WorkspaceMemory[Workspace Memory Layer]
RepoMap[REPO_MAP md]
Changelog[CHANGELOG md]
Decisions[DECISIONS md]
Patterns[PATTERNS md]
Debugging[DEBUGGING md]
Todo[TODO md]
Soul[SOUL md]
end
Code --> RepoMap
Code --> Changelog
Code --> Decisions
Code --> Patterns
Code --> Debugging
Code --> Todo
Code --> Soul
RepoMap --> Changelog
RepoMap --> Decisions
RepoMap --> Patterns
Decisions --> Patterns
Debugging --> Decisions
Debugging --> Todo
Component Structure
Workspace Memory Layer
[!IMPORTANT] Changes in
workspace/*.mdare part of the repository’s internal memory system. They should stay aligned with the codebase and the repo structure, but they do not replace product-facing or operational documentation.
The files in workspace/ form a compact, persistent set of engineering notes. Each file has a single job, and the update rules are explicit so the memory layer stays short, current, and high-signal.
REPO_MAP.md
workspace/REPO_MAP.md
This is the structural anchor for the repository. It lists the major top-level areas and the other workspace memory files, so future sessions can orient themselves quickly.
| Topic | Details |
|---|---|
| Purpose | Compact map of the repository structure |
| Core content | Root-level areas and workspace memory files |
| Root-level areas recorded | application/, backend/, data/, db/, documents/, frontend/, openapi/, packages/openapi/, platform/, scripts/, services/, workspace/ |
| Update trigger | New top-level directory, service rename, or major move |
| Update sequence | Update REPO_MAP.md, then CHANGELOG.md, and, if needed, PATTERNS.md and DECISIONS.md |
| Role in memory system | Primary navigation map for the rest of the workspace docs |
What belongs here
- High-level repository layout
- Major folders and their purpose
- The workspace memory file list
- The update protocol for structural changes
CHANGELOG.md
workspace/CHANGELOG.md
This file tracks notable project-level changes so future sessions can quickly see what changed, why it changed, and where to look next.
| Topic | Details |
|---|---|
| Purpose | Record notable project updates |
| Format | YYYY-MM-DD, change title, type, summary, files/areas, validation, follow-up |
| Allowed types | Feature, Fix, Refactor, Docs, Infra, Breaking Change |
| Update trigger | Important repository updates that are worth preserving |
| Ordering | Newest entries first |
| Size control | Keep under 300 lines; summarize or prune older entries when needed |
What belongs here
- Significant changes to repo structure or workflows
- High-value documentation updates
- Infrastructure or architecture changes that future sessions should know about
- Validation notes that confirm a change was checked
DECISIONS.md
workspace/DECISIONS.md
This file is the repository’s single source of truth for major technical and architectural decisions.
| Topic | Details |
|---|---|
| Purpose | Capture significant decisions and the reasoning behind them |
| Format | YYYY-MM-DD, status, context, decision, alternatives considered, consequences |
| Allowed statuses | Accepted, Superseded, Deprecated |
| Update trigger | Significant technical or architectural decision |
| Size control | Keep under 300 lines; prune or summarize when necessary |
What belongs here
- Architecture choices
- Framework or library selections
- Non-trivial implementation approaches
- Reversed or superseded decisions
- Workarounds chosen because of external limitations
PATTERNS.md
workspace/PATTERNS.md
This file records reusable conventions and standards that should be applied consistently across the codebase.
| Topic | Details |
|---|---|
| Purpose | Capture recurring patterns, conventions, and technical standards |
| Status values | Active, Deprecated |
| Categories present | Architecture, Data Flow, Error Handling, Testing, API Design, File Structure, Other |
| Update trigger | A pattern is introduced, adopted, replaced, or deprecated |
| Scope rule | Only document patterns that should be replicated, not one-off implementations |
| Size control | Keep under 300 lines |
What belongs here
- Repeatable architecture patterns
- Error handling conventions
- Testing approaches
- API shape and file structure conventions
- Integration standards that define how new code should fit in
DEBUGGING.md
workspace/DEBUGGING.md
This file captures troubleshooting knowledge and issue history in a compact incident format.
| Topic | Details |
|---|---|
| Purpose | Track symptoms, investigation steps, causes, and fixes |
| Format | YYYY-MM-DD, issue title, status, symptoms, environment, root cause, investigation steps, solution, prevention, related |
| Allowed statuses | Open, Investigating, Fixed, Recurring, Won’t Fix |
| Main sections | Current Issues, Resolved Issues |
| Update trigger | A reproducible issue, debugging session, or resolved incident |
| Size control | Keep under 300 lines |
What belongs here
- Error symptoms and stack traces
- Investigation steps and outcomes
- Root cause analysis
- Fixes and workarounds
- Prevention notes tied to future troubleshooting
TODO.md
workspace/TODO.md
This file powers chat suggestion chips and keeps the next actions short, concrete, and actionable.
| Topic | Details |
|---|---|
| Purpose | Maintain a small set of high-signal next actions |
| Format | Each task must be wrapped in <todo> tags |
| Task content | First line: title; second line: optional description |
| Update behavior | Maintain proactively after each response |
| Selection rule | Add only concrete, project-specific next steps |
| Capacity rule | Usually keep 1–3 strong tasks; avoid filler |
| Maintenance rule | Remove or rewrite stale, duplicated, or lower-priority tasks |
What belongs here
- Specific follow-up work tied to real repository needs
- Short, actionable tasks that can guide the next session
- Re-ranked items based on current urgency and impact
SOUL.md
workspace/SOUL.md
This file holds behavioral and tone guidance for the assistant session. It is meant to be evolved over time as the repository memory system matures.
| Topic | Details |
|---|---|
| Purpose | Store instructions about tone, boundaries, and working style |
| Structure | <instructions> and <soul> blocks |
| Content | Core truths, boundaries, and vibe guidance |
| Update trigger | When the assistant learns or adopts a better working style |
| Special rule | If this file changes, the change should be surfaced to the user |
Update Protocol
[!IMPORTANT]
SOUL.mdis the only workspace memory file that explicitly requires the change to be disclosed to the user when it is modified.
The workspace memory layer follows a simple update hierarchy.
-
Structural change in the repository
- Update
REPO_MAP.mdfirst. - Log the change in
CHANGELOG.md. - If the change introduces a reusable convention, update
PATTERNS.md. - If the change reflects a major trade-off or implementation choice, update
DECISIONS.md.
- Update
-
New or revised convention
- Capture the pattern in
PATTERNS.md. - If the convention came from a specific trade-off, record the decision in
DECISIONS.md.
- Capture the pattern in
-
Notable incident or debugging session
- Record the problem in
DEBUGGING.md. - If the fix created a durable architectural choice, add it to
DECISIONS.md. - If the investigation revealed a reusable pattern, add it to
PATTERNS.md.
- Record the problem in
-
Next-step maintenance
- Refresh
TODO.mdwith only the highest-value follow-ups. - Remove stale or completed tasks promptly.
- Refresh
-
Tone or behavioral memory
- Update
SOUL.mdonly when the session’s working style meaningfully changes. - If
SOUL.mdchanges, tell the user.
- Update
sequenceDiagram
participant Dev as Agent
participant Repo as Repository Change
participant RepoMap as REPO_MAP md
participant Changelog as CHANGELOG md
participant Decisions as DECISIONS md
participant Patterns as PATTERNS md
participant Debugging as DEBUGGING md
participant Todo as TODO md
participant Soul as SOUL md
Dev->>Repo: Inspect changed files and context
Dev->>RepoMap: Update structure for directory or service changes
Dev->>Changelog: Record the notable update
Dev->>Decisions: Record trade-offs and reversals
Dev->>Patterns: Record reusable conventions
Dev->>Debugging: Record incident details when needed
Dev->>Todo: Refresh high-value next actions
Dev->>Soul: Adjust behavior guidance when needed
Dev-->>Repo: Persist the workspace memory layer
How the Workspace Memory Layer Fits the Repository
The memory layer complements the repository’s product and operational documentation instead of replacing it.
| Workspace memory file | What it captures |
|---|---|
REPO_MAP.md |
Repository structure and navigation |
CHANGELOG.md |
Notable project changes and validation notes |
DECISIONS.md |
Architectural and implementation trade-offs |
PATTERNS.md |
Reusable engineering conventions |
DEBUGGING.md |
Troubleshooting history and incident learnings |
TODO.md |
Current high-value follow-up work |
SOUL.md |
Session tone and behavior guidance |
| Other documentation area | What it should continue to capture |
|---|---|
| Product and feature docs | User workflows, business behavior, and product intent |
| Operational docs | Deployment, monitoring, runbooks, and runtime procedures |
| API and integration docs | Contracts, request/response details, and service interactions |
Repository docs outside workspace/ |
Broader implementation notes that do not belong in persistent memory |
Key Classes Reference
| Class | Responsibility |
|---|---|
REPO_MAP.md |
Repository structure map and memory file index |
CHANGELOG.md |
Notable project-level change log |
DECISIONS.md |
Durable architectural and implementation decisions |
PATTERNS.md |
Repeatable engineering patterns and conventions |
DEBUGGING.md |
Troubleshooting records and incident history |
TODO.md |
High-signal next actions for follow-up |
SOUL.md |
Session tone, boundary, and behavior guidance |