Skip to content

docs: Update data/brain storage layout in brain-system.md and ARCHITECTURE.md to collectionStore format #5436

Description

@atomantic

Problem

In docs/features/brain-system.md:63-83 and docs/ARCHITECTURE.md:114-122:
The Data Storage directory trees depict Brain entity records as monolithic JSON files (people.json, projects.json, ideas.json, admin.json, inbox.json, links.json, journals.json, memories.json, buckets.json).
In server/services/brainStorage.js:5-16, 58-77, Migration 200 (issue #725) refactored all entity stores into collectionStore directories (data/brain/<type>/<id>/index.json with a schema-version stamped data/brain/<type>/index.json). The monolithic .json files are legacy files from before migration 200.
Additionally, docs/features/brain-system.md:291 describes server/routes/brain.js as an aggregator mounting subrouters but omits brainIdeaLoom.js (ideaLoomRoutes, mounted at server/routes/brain.js:20, 26).

Trigger

Developers, operators, or autonomous CoS agents reading docs/features/brain-system.md or docs/ARCHITECTURE.md to locate Brain data files on disk for inspection, backup, or manual migration.

Impact

Users and agents looking for data/brain/people.json or data/brain/inbox.json find only 20-byte legacy stubs or .bak-200 files instead of the actual active records in data/brain/<type>/<id>/index.json, leading to mistaken data loss diagnosis.

Fix

  1. In docs/features/brain-system.md:65-82 and docs/ARCHITECTURE.md:114-122, update the data/brain/ layout diagram to show the per-record collectionStore directory structure:
./data/brain/
├── meta.json               # Settings and scheduler state
├── admin/                  # Admin tasks (collectionStore: <id>/index.json)
├── buckets/                # Custom bucket definitions (collectionStore: <id>/index.json)
├── ideas/                  # Ideas and concepts (collectionStore: <id>/index.json)
├── inbox/                  # Captured thoughts (collectionStore: <id>/index.json)
├── journals/               # Daily Log entries (collectionStore: <id>/index.json)
├── links/                  # Cross-record links (collectionStore: <id>/index.json)
├── memories/               # Brain memories (collectionStore: <id>/index.json)
├── people/                 # People records (collectionStore: <id>/index.json)
├── projects/               # Projects with status tracking (collectionStore: <id>/index.json)
├── songs/                  # SongBook songs (collectionStore: <id>/index.json)
├── memory-bridge-map.json  # Brain↔CoS memory bridge mapping
├── obsidian-vaults.json    # Obsidian vault sync config
├── sync_log.jsonl          # Obsidian sync history
├── digests.jsonl           # Daily digest history
└── reviews.jsonl           # Weekly review history
  1. In docs/features/brain-system.md:291, update the router description table to include brainIdeaLoom.js (ideaLoomRoutes).
    (Rejected alternative: Leaving the file tree diagram unedited was rejected because it directly misrepresents the on-disk storage layout established in migration 200.)

Acceptance criteria

  • docs/features/brain-system.md and docs/ARCHITECTURE.md show the collectionStore directory layout for Brain entity stores.
  • docs/features/brain-system.md lists brainIdeaLoom.js among server/routes/brain.js subrouters.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationeffort:lowEffort: lowmodel:lightModel size: lightplanTracked by /do:replan

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions