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:
- Update
workspace/REPO_MAP.mdfirst. - Add a concise note to
workspace/CHANGELOG.md. - Update
workspace/PATTERNS.mdif a reusable convention changed or was added. - Update
workspace/DECISIONS.mdif the change reflects a significant trade-off or architecture choice. - Update
workspace/DEBUGGING.mdif the change came from an incident or troubleshooting session. - Refresh
workspace/TODO.mdso 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.mdentry. - Add a
workspace/PATTERNS.mdentry when the change introduces a reusable convention. - Add a
workspace/DECISIONS.mdentry 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 IssuesResolved Issues
Those sections separate active troubleshooting from historical incident records.
Maintenance Rules
- Use
Recurringwhen 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:
- A map of the repository.
- A record of why important choices were made.
- 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 |