Internal Workspace and Project Memory
Overview
The workspace/ folder is the repository’s long-lived operating memory. It is split into four durable document types: mission and norms in SOUL.md, dated observations in MEMORIES.md, stable architectural or product commitments in DECISIONS.md, and follow-up work in TASKS.md. workspace/README.md explains how those files work together and defines the update rule that keeps them aligned with code changes.
This workspace discipline is part of the repo’s change-management process, not an optional documentation sidecar. When you make a meaningful docs or code change, you are expected to update at least one workspace memory file in the same commit, and scripts/check-workspace-memory.mjs enforces that rule through pnpm workspace:check-memory.
Architecture Overview
flowchart TD
Change[Meaningful code or docs change] --> Diff[Collect changed files]
Diff --> Check[scripts/check-workspace-memory.mjs]
Check --> Meaningful{Touches tracked paths for enforcement}
Meaningful -->|No| Skip[Exit 0 skip]
Meaningful -->|Yes| Memory{Touches workspace memory files}
Memory -->|Yes| Pass[Exit 0 pass]
Memory -->|No| Fail[Exit 1 fail]
subgraph WorkspaceMemory[Workspace memory files]
Readme[workspace README]
Soul[workspace SOUL]
Memories[workspace MEMORIES]
Decisions[workspace DECISIONS]
Tasks[workspace TASKS]
end
Check -.-> Readme
Check -.-> Soul
Check -.-> Memories
Check -.-> Decisions
Check -.-> Tasks
Workspace Files
README.md
[!NOTE]
scripts/check-workspace-memory.mjstreatsworkspace/README.mdas a valid memory file alongsideSOUL.md,MEMORIES.md,DECISIONS.md, andTASKS.md.
workspace/README.md
README.md is the entry point for the workspace memory folder. It explains the folder’s purpose, names each memory file, and states the update rule that keeps the repository’s operating memory current.
- Defines the workspace as the repo’s long-lived operating memory, described as the project’s “second employee.”
- Names the purpose of each file:
SOUL.mdfor mission and principlesMEMORIES.mdfor dated observationsDECISIONS.mdfor durable decisionsTASKS.mdfor follow-up work
- States the update rule:
- every meaningful docs or code change should update at least one workspace file
- the update should happen in the same commit
- Links that rule to
pnpm workspace:check-memoryandscripts/check-workspace-memory.mjs
SOUL.md
workspace/SOUL.md
SOUL.md captures the project’s mission and working principles. It is the most stable memory file for documentation intent and scoping norms.
- Mission
- Keep API docs clear for integrators
- Prefer explicit scoping language for all user/applicant-bound data
- Reduce ambiguity between tenant-level and applicant-level behavior
- Working principles
- Write docs in second person and active voice
- Call out security and data-scope constraints near endpoint descriptions
- When scope is token-derived, say so directly and state whether caller-supplied IDs are accepted
- Treat workspace memory updates as part of done criteria for each meaningful change
- Update cadence
- Update this file when the mission or documentation principles change
- Update at least one workspace file on each meaningful change so project context compounds over time
MEMORIES.md
workspace/MEMORIES.md
MEMORIES.md is the dated observation log. It is meant for short notes that should influence future edits and keep context from being lost across changes.
- Purpose
- Append short dated notes
- Record observations that should affect later edits
- Entry template
- Date
- Context
- What changed
- Why it matters next time
- Recorded memories
- 2026-03-24
- Clarified that balances and transactions endpoints are applicant-scoped by consent token
- Documented that those endpoints do not accept
applicant_idquery params - Corrected US and JP regional namespace examples to avoid ambiguous
/api/v1/-only paths - Added the enforcement check (
pnpm workspace:check-memory) so workspace memory is updated with future meaningful changes
- 2026-03-31
- Added a dedicated sandbox seeding script that creates a tenant, API client, credit profiles, decisions, and US/JP consent evidence fixtures
- Added
pnpm seed:sandboxas the canonical shortcut and documented environment variable overrides in the root README - Tightened sandbox fixtures to be deterministic and idempotent
- Aligned decision outcomes with profile and evidence metrics so credit reviewers see coherent outputs
- Added JSON and CSV export output for seeded fixtures so reviewers can inspect dummy data directly without querying the database
- 2026-03-24
DECISIONS.md
workspace/DECISIONS.md
DECISIONS.md is the durable decision log. It captures stable architectural or product choices that should continue to shape documentation and implementation.
| Decision ID | Status | Date | Decision | Consequence |
|---|---|---|---|---|
| ADR-0001 | Accepted | 2026-03-24 | GET /data/balances and GET /data/transactions identify the applicant from the Bearer access token’s consent context. |
Docs must explicitly state that no applicant_id parameter is required or accepted for these reads. |
TASKS.md
workspace/TASKS.md
TASKS.md is the follow-up queue. It records open work that should stay visible until it is addressed or consciously retired.
| Status | Item |
|---|---|
| Backlog | Add similar token-scope clarification to income/account summary pages |
| Backlog | Add one cross-link from data endpoints to consent creation docs (applicant_id origin) |
| Backlog | Define ownership/process for updating workspace memory files during PR reviews |
Change-Management Enforcement
check-workspace-memory.mjs
scripts/check-workspace-memory.mjs
This script enforces the workspace update rule. It inspects changed files, decides whether the change is meaningful for documentation or code, and fails the run if no workspace memory file changed alongside that work.
Script behavior
| Function / Constant | Description |
|---|---|
memoryFiles |
Set of files that satisfy the workspace memory rule: workspace/SOUL.md, workspace/MEMORIES.md, workspace/DECISIONS.md, workspace/TASKS.md, and workspace/README.md |
lines(text) |
Splits command output into trimmed, non-empty lines |
sh(cmd) |
Executes a shell command with execSync and returns trimmed stdout |
changed |
Combined list of modified, staged, and untracked files considered by the script |
meaningfulTouched |
Boolean that becomes true when touched files match apps/, packages/, docs/, documents/, scripts/, or package.json |
memoryTouched |
Boolean that becomes true when any changed file is in memoryFiles |
File discovery flow
- Reads changed files from
git diff --name-only HEAD. - Adds untracked files from
git ls-files --others --exclude-standardso local edits count before staging. - Falls back to
git diff-tree --no-commit-id --name-only -r HEADif no changes were found. - Checks whether any changed file matches the meaningful-change rule.
- If the change is meaningful, checks whether at least one workspace memory file changed.
- Exits with a failure message if the rule was violated.
Runtime outcomes
| Outcome | Condition | Exit behavior |
|---|---|---|
| Skip | No tracked code or docs changes are detected | Logs workspace-memory-check: no tracked code/docs changes; skipping. and exits 0 |
| Pass | A meaningful change includes at least one workspace memory file | Logs workspace-memory-check: passed. and exits 0 |
| Fail | A meaningful change does not include a workspace memory file | Logs workspace-memory-check: failed. Update at least one workspace memory file (SOUL/MEMORIES/DECISIONS/TASKS/README) alongside meaningful changes. and exits 1 |
Change Flow
Meaningful change with workspace update
sequenceDiagram
participant Dev as Contributor
participant Git as Git status and diff
participant Check as scripts/check-workspace-memory.mjs
participant Memory as Workspace memory files
Dev->>Git: Make code or docs changes
Dev->>Check: Run pnpm workspace:check-memory
Check->>Git: Read diff and untracked files
Check->>Check: Classify meaningful touched paths
alt No meaningful tracked changes
Check-->>Dev: Skip and exit 0
else Meaningful change detected
Check->>Memory: Verify at least one memory file changed
alt Memory file changed
Check-->>Dev: Passed and exit 0
else No memory file changed
Check-->>Dev: Failed and exit 1
end
end
Workspace memory update cycle
stateDiagram-v2
[*] --> Idle
Idle --> Skipped: no meaningful touched
Idle --> Validating: meaningful touched
Validating --> Passed: memoryTouched
Validating --> Failed: !memoryTouched
Passed --> [*]
Failed --> [*]
Skipped --> [*]
Repository Norms Captured by the Workspace
The workspace files encode the repo’s documentation and change-management norms in a way that survives individual code changes.
SOUL.mdis the mission and style anchor for documentation authors.DECISIONS.mdrecords durable commitments, so later edits preserve previously accepted scoping rules.MEMORIES.mdcaptures short-lived but important observations that should influence future edits.TASKS.mdkeeps unresolved follow-up work visible.README.mddefines the system and links the files together.scripts/check-workspace-memory.mjsenforces that this memory layer evolves with meaningful repository change.
Error Handling
The enforcement script has a single hard failure mode: meaningful code or docs changes without a workspace memory update. In that case, the process exits with code 1 and prints a clear remediation message.
workspace-memory-check: failed. Update at least one workspace memory file (SOUL/MEMORIES/DECISIONS/TASKS/README) alongside meaningful changes.
When no tracked code or docs changes are detected, the script intentionally skips enforcement and exits successfully.
Dependencies
gitcommand-line output for change detectionpnpm workspace:check-memoryas the documented invocation path- Node.js
node:child_processforexecSync - Workspace documentation files:
workspace/README.mdworkspace/SOUL.mdworkspace/MEMORIES.mdworkspace/DECISIONS.mdworkspace/TASKS.md
Testing Considerations
Use these scenarios to validate the change-management rule:
- Touch
apps/,packages/,docs/,documents/,scripts/, orpackage.jsonwithout updating a workspace file: the script should fail. - Touch one of the workspace memory files alongside a meaningful change: the script should pass.
- Make only non-meaningful changes outside the enforced path set: the script should skip.
- Create an untracked workspace memory file locally: the script should count it because untracked files are included in the scan.
- Update
workspace/README.mdonly: the script should treat it as a valid memory-file update.
Key Classes Reference
| Class | Responsibility |
|---|---|
README.md |
Defines the workspace memory folder and the same-commit update rule |
SOUL.md |
Stores mission, scoping principles, and documentation norms |
MEMORIES.md |
Captures dated observations that should influence future edits |
DECISIONS.md |
Records durable architectural and product decisions |
TASKS.md |
Tracks follow-up work and open process items |
check-workspace-memory.mjs |
Enforces workspace memory updates for meaningful code and docs changes |