docs: Excavate architecture specs and align documentation#430
Merged
Conversation
Initial excavation of Memory Loop codebase using progressive discovery approach. Documents features from user perspective rather than code structure. Documented: - Ground tab (home dashboard) as container feature - Vault Selection infrastructure (entry gate, discovery, sessions) Discovered but not yet documented: - Configuration, Extraction (infrastructure) - Spaced Repetition, Inspiration (Ground sub-features) - Capture, Think, Recall tabs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extraction pipeline: - Overnight batch system (3am daily) extracts facts from transcripts - Sandbox pattern for safe SDK access to ~/.claude/rules/memory.md - Checksum-based idempotency prevents reprocessing Spaced Repetition: - Card generation via Claude Sonnet (daily/weekly/manual triggers) - SM-2 algorithm with 4-response model (Again/Hard/Good/Easy) - Widget state machine: loading → question → revealed → complete Also clarified vault-selection spec: two gear buttons exist (ConfigEditorDialog for per-vault, SettingsDialog for system settings) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Inspiration: - Contextual prompts (daily, weekday reflection vs weekend creative) - Quotes (weekly, context-aware from vault notes) - Weighted random selection favoring recent prompts - Click to prefill Discussion mode System Settings (three tabs): - Memory Editor: ~/.claude/rules/memory.md with 50KB limit - Extraction Prompt: customize fact extraction with override pattern - Card Generator: requirements prompt + weekly byte limit slider Both use override pattern: custom file overrides default, reset deletes override. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Configuration (per-vault .memory-loop.json): - Editable: title, subtitle, badges, model, inspiration settings - Non-editable via UI: path fields (require manual JSON) - File not created if all values match defaults Capture tab: - Quick notes to daily files with [HH:MM] timestamps - Meeting mode routes to dedicated meeting files - Draft auto-save to localStorage - Platform-aware keyboard (Enter submits on desktop, newline on mobile) - Stopping meeting auto-navigates to Think with /expand-note prefilled Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Think tab: - Streaming AI chat via WebSocket + Claude Agent SDK - Session persistence with metadata + transcript files - Slash commands with autocomplete, tool display inline - Transcripts feed into Extraction pipeline Recall tab: - File tree with lazy-loaded directories - Multiple viewers (markdown, images, video, PDF) - Wiki-link navigation, search (name + content) - Multi-layer security against path traversal Pair Writing (accessed from Recall): - Split-pane: Editor + Discussion (shared session with Think) - Quick Actions: Tighten, Embellish, Correct, Polish (Edit tool) - Advisory Actions: Validate, Critique, Compare, Discuss (feedback) - Snapshot for comparison, desktop only Excavation complete: 11 features documented across 4 infrastructure and 7 user-facing specs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Communication Layer: - Documents REST vs WebSocket split with accurate endpoint paths - Vault-scoped routes under /api/vaults/:vaultId/ - Global routes (health, vaults list, session lookup, assets) - Session management split between REST (lookup/delete) and WebSocket (create/resume/message) - Connection lifecycle, auto-reconnect, state management Card Generator: - Automated Q&A extraction from vault markdown using Claude Sonnet - Three-pass scheduling: daily (recent), weekly (backfill), manual - Cost controls: weekly byte budget, content limits, skip patterns - SHA-256 checksum deduplication - Concurrency control and error handling Updates Spaced Repetition spec to reference Card Generator for detailed generation logic. Excavation complete: 13 specs (7 features + 6 infrastructure). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix meeting endpoints in Capture spec (was /start /stop /state, now POST /meetings, DELETE /current, GET /current) - Add Tasks Widget section to Home Dashboard (PARA scanning, extended checkbox states, API endpoints) - Add Health Panel section to Home Dashboard (dismissal flow) - Add Setup Wizard section to Vault Selection (6-step process, idempotent behavior) - Update entry points tables and excavation index Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Task List was incorrectly documented as a widget in home-dashboard.md. It is actually an alternative view within the Recall tab, toggled via the tree pane header. - Create task-list.md with full feature documentation - Remove erroneous Tasks Widget section from home-dashboard.md - Add View Toggle section to recall.md linking to task-list.md - Update excavation index with new feature Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add _overview.md as entry point for learning the codebase. Covers what Memory Loop is, the GCTR philosophy, architecture overview, and a reading path through other specs. Add navigation-bar.md documenting how the four-tab toolbar embeds the GCTR framework into the UI. Update excavation index with "Start Here" callout and simplified architecture notes that reference the new overview. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update feature names from internal (Home/Note/Chat/View) to user-facing GCTR names (Ground/Capture/Think/Recall) with sigils. Add action-oriented descriptions that mention sub-features. Clarify two-channel communication pattern (REST + WebSocket). Link to system overview specs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
…es; delete sync documentation and example configuration for BoardGameGeek integration.
Fix documentation gaps identified during spec-vs-usage review: - capture.md: Fix daily note format to show actual ## Capture heading with [HH:MM] bullet list (was showing incorrect timestamp format) - ground.md: Add Health Panel section, fix goals path reference to use vault.goalsPath instead of hardcoded goals.md - think.md: Add Structured Questions (AskUserQuestion) section, fix attachment upload path - recall.md: Expand context menu from 2 to 8 actions, add full Pair Writing section with Quick/Advisory actions and snapshots - README.md: Change "four tabs" to "four modes" for consistency Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Widgets feature not implemented in Recall tab. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Restructure Recall documentation: - Move docs/usage/recall.md to docs/usage/recall/README.md - Extract Pair Writing section to docs/usage/recall/pair-writing.md - Update links in docs/usage/README.md This allows future expansion of Recall documentation while keeping Pair Writing as a standalone reference. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds Date and Authors fields to match ADR 0001 format, providing clear historical context for the baseline metrics. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Refreshed project documentation while retaining critical guidance: - Fake timers pattern for deterministic tests - SDK provider pattern to prevent accidental API calls - Parallel test limitation warning - Documentation maintenance requirements Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove broken links to docs/widgets/README.md (removed in e6d09ab) - Add testing constraints to copilot-instructions.md: parallel execution, mock.module() warning, SDK provider pattern Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Add three diagrams to visualize key system flows: - session-auto-resume: REST lookup + WebSocket establishment - websocket-connection-lifecycle: connect, operate, reconnect, cleanup - gctr-mode-transitions: mode switching with data flow Update specs to reference diagrams: - communication-layer.md: both WebSocket diagrams - vault-selection.md: session auto-resume - _overview.md, navigation-bar.md: GCTR transitions Fix broken Configuration link in navigation-bar.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Expand Recall mode to show internal sub-state transitions: - Adjust Mode: Edit button → Save/Cancel - Pair Writing: Pair Write button → Exit Add documentation section explaining both sub-modes with their entry/exit patterns and purpose (Quick/Advisory Actions). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.lore/specs/system with 16 feature specifications following GCTR framework.sdd/task planning files (sync, spaced repetition, pair writing modes)docs/usage/guides with excavated specsCLAUDE.mdwith preserved testing patterns (fake timers, SDK provider, parallel warning)Test plan
.lore/specs/_overview.mdprovides readable architecture entry point🤖 Generated with Claude Code