T H E W A L K

Design Technologist,
AI Infrastructure,
Prototyping.

← Back to Projects
Platform
Platform

soul_view: TUI for Agentic Memory

Role
Sole engineer. Designed and built the registry schema and the TUI on top of it.
User Problem
AI coding sessions lose context every reset. I needed to see what each agent had planned, decided, and finished across every project, without leaving the terminal.
Business Problem
Agent memory is a real problem to solve at the application layer. Most attempts reach for vector stores. I wanted to see how far filesystem-as-source-of-truth could go before reaching for anything fancier.
Impact
31 projects, hundreds of sessions, all on disk. Powers daily agent workflows across Claude Code, Gemini CLI, and Pi.

What it does

soul_view, live walkthrough across Projects, Sessions, Memory, Decisions

Five tabs over a single source of truth: the filesystem.

  • Projects: 31 projects from PROJECTS.json, color-coded by pillar, session and task counts visible. Click to switch the active context.
  • Sessions: Per-project session detail covering intent, summary, next step, rationale, decisions, fixed-list, metrics.
  • Tasks: Status-grouped with glyphs and done-criteria.
  • Memory: Frontmatter parser pulling from each project’s ~/.claude/projects/*/memory/ directory.
  • Decisions: Flat log of /decision events with target as a cyan arrow and intent as a why-line.

A 2-second poll detects new files in the active project, fires a Textual toast, and auto-highlights the new row. Press o on any row to open the underlying file in the default app.

Why a TUI over a web UI

The registry is local. The agents writing to it are local. A TUI removes the round-trip. Launch it inline with the agent session, see the same files the agent sees, no auth, no server, no cold start.

Architecture

The registry is the contract; the TUI is one view of it. Other tools (the soul CLI’s pulse and finalize commands, the kernel hooks) consume the same files.

  • State: local session registry directory ~/soul_registry/ (sessions, tasks, decisions, memory, telemetry, signals)
  • Authority: ~/dotfiles/soul/config/PROJECTS.json
  • Viewer: ~/dotfiles/soul/kernel/soul_view.py on Textual + rich, dedicated venv at ~/dotfiles/soul/.venv
  • Live watcher: 2s set_interval polling, diffs against snapshot, Textual toast notifications, auto-refresh of affected tabs

What broke during testing

Three things came up that are worth naming:

  1. Markup escapes. Rich’s bracket-bearing content (e.g. [/Option+] in a user prompt, or [Image: source: ...] auto-attachments) blows up Textual’s content-markup parser. Wrapped every dynamic interpolation in rich.markup.escape().
  2. Shape drift. Some task JSONs had top-level lists where I expected dicts; some done_criteria were strings, not arrays. Added _as_list / _as_dict helpers and defensive isinstance checks at every read point.
  3. Focus loops. Project-tab Selected events fed back into the focus handler. Fixed with event.stop() plus a focus-aware tab activation.

What it’s part of

soul_view is the user-facing surface of Soul OS, the broader system I run on top of the local agentic stack. Soul OS treats the filesystem as the source of truth for agent memory: no vector store, no SaaS, every session a grep-able JSON file you can read three months later and see exactly what was planned, what happened, and why.

Artifact Evidence

📎 soul-view.mp4

Project: soul-view

Access Restricted

Access Required

Enter the access key to view projects

Hint: See intro email for access key.