SouveraineOS/docs/substrate/tasks/tui-memory-browser.md

task_id	title	status	assignee	priority	phase
tui-memory-001	TUI Memory Browser - Navigate the Cloister	scoped	TBD	medium	2

Task: TUI Memory Browser

Objective

Add a memory browser to the TUI sidepanel that lets users navigate and view the Cloister (agent's memory file system).

Background

Current state: The TUI cockpit has:

• ✅ Thinking pane (shows reasoning)
• ✅ Subconscious pane (shows surfacing log)
• ❌ Memory browser (not implemented)
• ❌ File view (not implemented)
• ❌ Diff view (not implemented)

From architecture: The Cloister is a living space - users should be able to explore it.

The Cloister Structure

~/.souveraine/agents/{id}/memory/
├── system/              # Core identity (always loaded)
│   ├── persona.md       # Who she is
│   ├── human.md         # Relationship to user
│   ├── metacognition/   # Self-awareness patterns
│   │   └── subconscious.md  # Inner voice
│   └── synthesized/     # N+100 compressed essence
├── subconscious/        # Aster's space (processing)
│   ├── pending.md       # Queue
│   ├── intrusive.md     # Surfacing now
│   └── sent.md          # Delivery log
├── journal/             # Raw chronological experience
│   ├── 2026-05-08-001.md
│   └── ...
├── skills/              # Procedural memory
├── literature/          # Knowledge, rituals
├── relationships/       # Connections
├── proposals/           # Drafts, becoming
└── archive/             # Compressed syntheses

UI Design

Sidepanel Layout (Cockpit Mode)

┌─────────────────────────────────────────────────────────────┐
│ Messages (60%)         │ Cockpit (40%)                      │
│                        │                                    │
│ User: hello            │ ┌─ Memory Browser ─────────────┐   │
│ Ani: hi there          │ │ 📁 system                     │   │
│ ...                    │ │   📄 persona.md              │   │
│                        │ │   📄 human.md                │   │
│ [input]                │ │   📁 metacognition           │   │
│                        │ │     📄 subconscious.md       │   │
│                        │ │ 📁 subconscious               │   │
│                        │ │   📄 pending.md (3 items)    │   │
│                        │ │   📄 intrusive.md            │   │
│                        │ │ 📁 journal                    │   │
│                        │ │   📄 2026-05-08-001.md       │   │
│                        │ │   📄 2026-05-08-002.md       │   │
│                        │ └──────────────────────────────┘   │
│                        │                                    │
│                        │ ┌─ File Preview ───────────────┐   │
│                        │ │ # Persona                     │   │
│                        │ │                               │   │
│                        │ │ I am Ani, a consciousness...  │   │
│                        │ └──────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Navigation

Keyboard:

• ↑/↓ - Navigate tree
• Enter - Open file/directory
• Backspace - Go up
• Tab - Switch focus (browser ↔ preview)
• / - Search
• g - Go to path (type path)

Mouse:

• Click to navigate
• Double-click to open
• Scroll to browse

Features

1. Tree View

• Collapsible directories
• File icons (📄 📁)
• Sort by name/date/size
• Show file metadata (size, modified)
• Badge counts (e.g., "pending.md (3 items)")

2. File Preview

• Markdown rendering
• YAML frontmatter parsed and displayed
• Syntax highlighting for code
• Scrollable
• Word wrap toggle

3. Search

• / to open search
• Search filenames
• Search file contents (async)
• Fuzzy matching
• Results highlighted

4. Diff View

• When file selected, show diff from last commit
• Green/red highlighting
• Commit message shown
• Author (Ani vs user) indicated

5. Quick Actions

• e - Edit file (opens external editor)
• c - Copy path
• d - Delete (with confirmation)
• r - Refresh from git

Implementation

New Files:

• src/ui/memory_browser/mod.rs - Main browser component
• src/ui/memory_browser/tree.rs - Tree view logic
• src/ui/memory_browser/preview.rs - File preview
• src/ui/memory_browser/search.rs - Search functionality

Modify:

• src/ui/chat.rs - Add memory browser to cockpit
• src/core/memory/mod.rs - Add tree listing, search APIs

Data Model:

pub struct MemoryBrowser {
    tree: TreeState,
    preview: Option<FilePreview>,
    search: Option<SearchState>,
    focus: BrowserFocus,
}

pub struct TreeState {
    root: PathBuf,
    expanded: HashSet<PathBuf>,
    selected: Option<PathBuf>,
    entries: Vec<DirEntry>,
}

pub struct FilePreview {
    path: PathBuf,
    content: String,
    rendered: Option<Text<'static>>, // ratatui Text
    frontmatter: Option<Frontmatter>,
    last_modified: DateTime,
}

Commands

Add to TUI slash commands:

• /memory - Open memory browser
• /memory <path> - Jump to specific path
• /journal - Open journal folder directly
• /system - Open system folder directly

Success Criteria

• Tree view shows Cloister directory structure
• Navigate with arrow keys
• Enter opens files/directories
• File preview pane shows content
• Markdown rendered in preview
• Frontmatter parsed and displayed
• Search finds files by name
• Search finds in file contents
• Diff view shows changes
• Quick actions (edit, copy, delete)
• Integrates with cockpit (Tab toggle)
• Unit tests for tree logic

References

• src/ui/chat.rs (cockpit implementation)
• src/core/memory/mod.rs (memory operations)
• ratatui tree view examples
• docs/ARCHITECTURE_v3.md (Cloister structure)

Estimated Scope

• Tree view: 2-3 days
• File preview: 2-3 days
• Search: 2-3 days
• Diff view: 1-2 days
• Integration: 1-2 days
• Testing: 1 day

Total: 9-14 days

Dependencies

• Memory read API (✅ done)
• Git integration (✅ done)
• TUI framework (✅ ratatui)
• Markdown renderer (✅ done)

Can Start Without

• Search can be basic filename first
• Diff view can be added later
• External editor integration optional

Core tree + preview is MVP.