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/*.md are 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.md is 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.

  1. Structural change in the repository

    • Update REPO_MAP.md first.
    • 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.
  2. 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.
  3. 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.
  4. Next-step maintenance

    • Refresh TODO.md with only the highest-value follow-ups.
    • Remove stale or completed tasks promptly.
  5. Tone or behavioral memory

    • Update SOUL.md only when the session’s working style meaningfully changes.
    • If SOUL.md changes, tell the user.
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