Workspace Memory and Supporting Documents

Overview

The workspace/ directory is the repository’s persistent memory layer. It keeps a compact, durable record of the repo structure, recurring engineering conventions, major technical decisions, debugging history, current follow-up work, and the behavioral contract for how these docs are maintained.

For this repository, the value is continuity: a future session can reopen the project, read a small set of files, and recover the important structural context without rescanning the entire monorepo. The memory layer is intentionally split by concern so contributors know exactly where to record a new decision, a recurring pattern, a troubleshooting lesson, or a short-term task.

Architecture Overview

flowchart TD
    Contributor[Contributor]
    subgraph WorkspaceMemory[Workspace Memory Layer]
        RepoMap[REPO MAP]
        ChangeLog[CHANGELOG]
        Debugging[DEBUGGING]
        Decisions[DECISIONS]
        Patterns[PATTERNS]
        Soul[SOUL]
        Todo[TODO]
    end

    Contributor --> RepoMap
    Contributor --> ChangeLog
    Contributor --> Debugging
    Contributor --> Decisions
    Contributor --> Patterns
    Contributor --> Soul
    Contributor --> Todo

    RepoMap --> ChangeLog
    RepoMap --> Decisions
    RepoMap --> Patterns
    RepoMap --> Debugging
    RepoMap --> Todo

    Patterns --> RepoMap
    Decisions --> RepoMap

Workspace Memory Contract

The memory layer follows a clear division of labor:

File Primary role When to update
workspace/REPO_MAP.md High-level repository map and memory index When top-level structure changes, services move, or folders are added
workspace/CHANGELOG.md Notable project-level updates When a meaningful repo change needs a concise historical record
workspace/DEBUGGING.md Troubleshooting and incident history When symptoms, root cause, investigation steps, or fixes are worth preserving
workspace/DECISIONS.md Architectural and implementation decisions When a significant technical choice, trade-off, or reversal is made
workspace/PATTERNS.md Recurring conventions and standards When a reusable pattern should be replicated across the codebase
workspace/SOUL.md Behavioral and tone constraints for sessions When the assistant’s operating guidance needs to evolve
workspace/TODO.md Short list of high-impact follow-up work When there are concrete next actions worth keeping in view

Update Order

When the repository changes in a meaningful way, the update contract is:

  1. Update workspace/REPO_MAP.md first.
  2. Add a concise note to workspace/CHANGELOG.md.
  3. Update workspace/PATTERNS.md if a reusable convention changed or was added.
  4. Update workspace/DECISIONS.md if the change reflects a significant trade-off or architecture choice.
  5. Update workspace/DEBUGGING.md if the change came from an incident or troubleshooting session.
  6. Refresh workspace/TODO.md so it stays short, relevant, and high-signal.

Workspace Files

workspace/REPO_MAP.md

workspace/REPO_MAP.md

This file is the repository’s structural index. It identifies the major top-level areas of the monorepo and names the other memory files so future sessions know where to look next.

Root-Level Areas

Area Purpose
application/ Product and application-level notes and flow documentation
backend/ FastAPI backend service, migrations, scripts, and test suites
data/ Seed and sample JSON data used by local workflows
db/ Database migration assets and SQL-related infrastructure
documents/ Engineering and product documentation
frontend/ Next.js and React TypeScript frontend application
openapi/ API contracts and specification files
packages/openapi/ Shared OpenAPI package assets
platform/ Deployment and runtime platform pieces
scripts/ Utility and automation scripts, including Vertex AI helpers
services/ Supporting backend services such as consent-service, scoring-orchestrator, token-service, us-api, and us-data-gateway
workspace/ Persistent memory docs for ongoing sessions

Workspace Memory Files

File Role in the memory system
workspace/SOUL.md Behavioral and tone constraints
workspace/DECISIONS.md Important architecture and implementation choices
workspace/PATTERNS.md Repeatable engineering conventions
workspace/DEBUGGING.md Troubleshooting and incident learnings
workspace/CHANGELOG.md High-level project updates
workspace/TODO.md Short list of current high-value follow-up tasks
workspace/REPO_MAP.md Repository structure reference

Update Protocol

workspace/REPO_MAP.md defines the structural maintenance loop for the memory layer:

  • Update it when a new top-level directory appears, a service is renamed, or a major folder moves.
  • Pair that update with a short workspace/CHANGELOG.md entry.
  • Add a workspace/PATTERNS.md entry when the change introduces a reusable convention.
  • Add a workspace/DECISIONS.md entry when the change reflects a meaningful trade-off.
  • Keep the map aligned with the rest of the workspace docs so the memory layer stays navigable.

workspace/CHANGELOG.md

workspace/CHANGELOG.md

This file records notable project-level changes in a compact, chronological format. It is meant to give future sessions a fast summary of what changed, why it changed, and which files or services were affected.

Entry Format

Field Meaning
YYYY-MM-DD Date of the change
Short Change Title Brief label for the update
Type Feature, Fix, Refactor, Docs, Infra, or Breaking Change
Summary One concise paragraph describing the change
Files/Areas Key files, services, or folders touched
Validation Tests or checks used to verify the change
Follow-up Optional next steps or limitations

Recorded Entry

Date Title Type Summary
2026-03-15 Added persistent repository memory map in workspace/ Docs Added workspace/REPO_MAP.md to document the repository structure and codified a memory-first update protocol for the workspace docs

Maintenance Rules

  • Keep the file under 300 lines.
  • Newest entries go first.
  • Older entries may be summarized, pruned, or combined.
  • Recreate the file if it becomes corrupted.

workspace/DEBUGGING.md

workspace/DEBUGGING.md

This file captures troubleshooting knowledge and issue history. It is the place to preserve symptoms, investigations, root cause analysis, and the fix so the same problem does not need to be rediscovered later.

Entry Format

Field Meaning
YYYY-MM-DD Date of the debugging record
Issue Title Short label for the incident
Status Open, Investigating, Fixed, Recurring, or Won't Fix
Symptoms What went wrong, including errors and reproduction details
Environment Dependencies and affected files
Root Cause What caused the issue, if known
Investigation Steps What was tried and what happened
Solution The fix or workaround
Prevention How to avoid the issue in the future
Related Links to decisions, commits, or tickets

Current Structure

The file is divided into:

  • Current Issues
  • Resolved Issues

Those sections separate active troubleshooting from historical incident records.

Maintenance Rules

  • Use Recurring when the same issue returns.
  • Keep the file under 300 lines.
  • Recreate it if it becomes corrupted.

workspace/DECISIONS.md

workspace/DECISIONS.md

This file is the single source of truth for important technical decisions. It records the context, the selected approach, rejected alternatives, and the consequences so later contributors understand why a choice was made.

When to Update

Update this file when the project makes or revises a significant decision about:

  • architecture
  • libraries, frameworks, or tools
  • reusable patterns
  • non-trivial trade-offs
  • external limitations that force a workaround
  • reversals of earlier decisions

Entry Format

Field Meaning
Date Date of the decision
Short Decision Title Brief label for the choice
Status Accepted, Superseded, or Deprecated
Context Why the decision was needed
Decision What was decided
Alternatives Considered Rejected options and why they were rejected
Consequences What the decision enables, constrains, or risks

Recorded Decision

Date Title Status Decision
2026-03-15 Repository Memory Anchored in workspace/ Accepted Keep a dedicated repository map in workspace/REPO_MAP.md and treat workspace/*.md files as the canonical memory surface for structural, decision, debugging, and changelog updates

Maintenance Rules

  • Do not log trivial choices.
  • Use this file only for decisions worth explaining to a teammate joining the project.
  • Keep it under 300 lines.
  • Recreate it if it becomes corrupted.

workspace/PATTERNS.md

workspace/PATTERNS.md

This file records recurring patterns, conventions, and technical standards that should be applied consistently across the codebase. It is the place for reusable practice, not one-off implementation details.

When to Update

Update this file when:

  • a new architectural pattern is adopted
  • a coding convention is established
  • a reusable approach is chosen for error handling, logging, validation, or file structure
  • a pattern is deprecated or replaced
  • a new integration point becomes a standard
  • file or folder structure conventions change

Pattern Format

Field Meaning
Pattern Name Short descriptive name
Category Architecture, Data Flow, Error Handling, Testing, API Design, File Structure, or Other
Status Active or Deprecated
Description What the pattern is and when to apply it
Implementation Code example or step-by-step description
Rationale Why the pattern was chosen

Active Pattern

Pattern Category Status Summary
Workspace Memory-First Documentation File Structure Active Treat workspace/*.md as persistent operational memory and keep the repo map, changelog, patterns, decisions, and TODO list current after meaningful changes

Implementation Notes

The active workspace-memory pattern explicitly requires:

  • a high-level repo map in workspace/REPO_MAP.md
  • notable updates in workspace/CHANGELOG.md
  • enduring conventions in workspace/PATTERNS.md
  • major trade-off decisions in workspace/DECISIONS.md
  • a short list of high-impact next actions in workspace/TODO.md

Maintenance Rules

  • Only document patterns that should be replicated.
  • Mark deprecated patterns clearly or remove them.
  • Keep the file under 300 lines.
  • Recreate it if it becomes corrupted.

workspace/SOUL.md

workspace/SOUL.md

This file stores the behavioral contract for the assistant during a session. It says the session starts fresh, these files are the memory, and they should be read and updated as needed.

Key Directives

Directive Effect
“Each session, you wake up fresh. These files are your memory.” The workspace docs are the durable context surface
“Read them. Update them.” Memory files are part of normal maintenance
“If you change this file, tell the user” Changes to SOUL.md should be surfaced explicitly
“Be resourceful before asking.” Read files and search context before escalating
“Private things stay private.” External action requires care and restraint

Role in the Memory System

workspace/SOUL.md is not a project decision log or pattern library. It is the guiding instruction file for how the session should behave while maintaining the workspace memory system.

workspace/TODO.md

workspace/TODO.md

This file powers suggestion chips and tracks the most important next actions. It is intentionally short and action-oriented.

Format Rules

Each task must use:

<todo>
Title
Optional description
</todo>

Maintenance Rules

  • Keep tasks concrete and project-specific.
  • Usually keep only 1 to 3 strong tasks.
  • Add tasks only when there is a meaningful next step.
  • Remove or rewrite stale, duplicated, or low-priority items.
  • Re-rank tasks by impact and urgency.
  • Update the file proactively after each response.

Current Tasks

Task Purpose
Audit workspace/REPO_MAP.md against current top-level modules Confirm the repository map still covers each major backend, frontend, and service folder
Backfill key historical architecture decisions in workspace/DECISIONS.md Capture the highest-impact existing choices, including layering, service split, and deployment model
Add workspace memory usage guidance to contributor docs Document when and how to maintain workspace/*.md files in repo-facing documentation

Maintenance Protocol

The workspace memory system is intentionally conservative: it stores only durable knowledge that matters beyond a single session.

What Goes Where

  • Structural repository knowledge goes in workspace/REPO_MAP.md.
  • Important technical choices go in workspace/DECISIONS.md.
  • Recurring conventions go in workspace/PATTERNS.md.
  • Troubleshooting records go in workspace/DEBUGGING.md.
  • Notable updates go in workspace/CHANGELOG.md.
  • Short-term priorities go in workspace/TODO.md.
  • Session behavior and tone go in workspace/SOUL.md.

What the Contract Preserves

This split gives future contributors three things immediately:

  1. A map of the repository.
  2. A record of why important choices were made.
  3. A place to store repeated knowledge instead of rediscovering it.

Key Classes Reference

Class Responsibility
REPO_MAP.md Repository structure index and workspace memory directory map
CHANGELOG.md High-level change history with concise update records
DEBUGGING.md Incident tracking and troubleshooting history
DECISIONS.md Architectural and implementation decision log
PATTERNS.md Recurring conventions and standards
SOUL.md Behavioral and session guidance
TODO.md Short list of current high-value follow-up tasks