feat(open, recall): actionable citations and palace resurfacing (Phase 3)

[therahul-yo]

Implements the core of REVAMP_PLAN Phase 3 (see #47): trust & recall UX.

superton open <id> — citations become actionable

Every answer footer shows 8-char drawer ids; until now they were dead text. open resolves them (new Memory.find_by_prefix, indexed LIKE-prefix lookup) and renders the full drawer — id, wing/room, created date with age, source, complete text:

╭────────────────────────── drawer ───────────────────────────╮
│ 4d53beb47a89ffee  notes/daily  ·  2026-07-06 17:43 (0d ago) │
│ note:20260706-174346                                        │
│                                                             │
│ smoke: open and recall                                      │
╰─────────────────────────────────────────────────────────────╯

• --edit opens the source file in $EDITOR when the source is a real file.
• Virtual sources (notes, transcript imports, web pulls) get a clear "the drawer above is the content" explanation instead of an error.
• Ambiguous prefixes list the candidates and exit 1; unknown ids exit 1 with a hint.

superton recall [--older-than N] — memory you forgot you had

Resurfaces random drawers as a staggered card cascade with age labels (today / yesterday / N days ago), backed by Memory.random_drawers with an optional age floor so --older-than 30 biases the walk toward the almost-forgotten. Ends with the superton open <id> follow-up hint, closing the loop with the feature above.

Validation

• 9 new tests in tests/test_open_recall.py (prefix resolution incl. empty-prefix guard, age-filtered sampling, open render / unknown id / virtual source / real $EDITOR launch via EDITOR=true, recall render + empty + age-floor states) — 271 passing total on this branch, ruff + mypy clean.

Note: independent of #48/#49; all branch from main, so later merges may need a trivial CHANGELOG/README conflict resolution — happy to rebase whichever lands last.

🤖 Generated with Claude Code

https://claude.ai/code/session_0145446GXbqRfpA4NF5Tn89E

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • Added superton open to look up drawers by short ID, show full details, and optionally open the source in your editor.
  • Added superton recall to resurface a random set of older drawers, with age-based filtering and quick follow-up guidance.
• Documentation
  • Updated the changelog and README to document the new commands and their usage.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
superton	Ready	Preview, Comment	Jul 6, 2026 5:44pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f4d615c2-6ec8-4e10-a75a-3007ae6e583d

📥 Commits

Reviewing files that changed from the base of the PR and between bac0ca4 and 2c8eef4.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• superton/cli.py
• superton/memory.py
• tests/test_open_recall.py

---

📝 Walkthrough

Walkthrough

This PR adds two new CLI commands, superton open and superton recall, backed by a new Memory.find_by_prefix method for resolving short drawer ids. It includes integration tests and updates to CHANGELOG.md and README.md documentation.

Changes

Open and Recall Feature

Layer / File(s)	Summary
Memory prefix lookup support superton/memory.py	Adds find_by_prefix for resolving short ids to drawers (ordered by recency), alongside existing random_drawers filtering logic.
CLI open and recall commands superton/cli.py	Adds open <id> [--edit] to resolve and display drawer details, optionally launching $EDITOR on the source file, and recall [--older-than N] to sample and display random drawers with age labels and hints.
Integration tests for open and recall tests/test_open_recall.py	Adds fixtures, a seeding helper, and tests covering find_by_prefix, random_drawers filtering, open command scenarios (success, unknown id, edit warnings/success), and recall scenarios (resurfacing, empty state, age filtering).
Documentation updates CHANGELOG.md, README.md	Documents the new superton open and superton recall commands and their options.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant Memory
  participant Editor

  User->>CLI: superton open id --edit
  CLI->>Memory: find_by_prefix(id)
  Memory-->>CLI: matched drawer
  CLI->>Editor: subprocess.run($EDITOR, source)
  Editor-->>User: file opened

  User->>CLI: superton recall --older-than N
  CLI->>Memory: random_drawers(older_than=N)
  Memory-->>CLI: sampled drawers
  CLI-->>User: reveal_cards output

Loading

Poem

A rabbit digs through drawers deep,
Finds old memories others let sleep 🐇
"open" jumps in, "recall" brings back the past,
Tests all green, docs updated fast,
Hop hop hooray, this burrow's built to last!

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}