diff --git a/docs/REVAMP_PLAN.md b/docs/REVAMP_PLAN.md new file mode 100644 index 0000000..a7e9476 --- /dev/null +++ b/docs/REVAMP_PLAN.md @@ -0,0 +1,129 @@ +# SuperTon Revamp Plan + +*The product bet, the feature tracks, and the release sequence. +Companion to `UX_PLAN.md` / `UX_ROADMAP.md`, which cover interaction +polish; this document covers what SuperTon becomes.* + +## The positioning problem + +Today SuperTon is a *tool you run*: you remember to `superton add` +things, then you ask. Khoj, mem0, AnythingLLM, and Obsidian-with-plugins +all live in that same "manual local RAG" space. + +The unique ground SuperTon is closest to — and nobody owns yet — is: + +> **The always-current, shared memory layer for every AI agent on your +> machine.** Claude Code, Cursor, and your own notes feed one palace +> automatically; every tool reads from it over MCP; and you can ask it +> about *time* ("what was I doing last Tuesday?"), not just topics. + +Three properties make that defensible: + +1. **Always current.** A palace you must feed by hand goes stale in a + week; one that feeds itself becomes infrastructure. +2. **Shared.** The MCP server already exposes 29 tools — the palace is + the one brain every agent on the machine can read and write. +3. **Temporal.** Verbatim drawers carry `created_at`; competitors + summarize away exactly the provenance that makes time queries work. + +Everything below is sequenced toward that. + +## Phase 1 — "It stays current by itself" *(v0.5)* + +The single biggest bet; it changes the product category from tool to +system. + +- **`superton watch`** — a watcher that monitors configured folders + *plus* the AI-tool transcript dirs the importers already understand + (`~/.claude/projects`, `~/.cursor`, `~/.amp`). New or changed files + auto-ingest within the polling interval. + - `superton watch add|remove|list` manages the watchlist. + - `superton watch --once` runs a single scan pass (cron-friendly and + trivially testable). +- **Incremental refresh** — mtime + size snapshots detect changed + files; a changed file is refreshed (forget + re-ingest) instead of + duplicated. Content-addressed drawer ids already make unchanged + chunks free. +- **Deletion is not forgetting.** A watched file that disappears keeps + its drawers — the palace is memory, not a mirror. `superton + forget-source` remains the explicit eviction path. +- Follow-ups: native FS events (watchfiles) instead of polling; + `superton watch install` for launchd/systemd persistence. + +## Phase 2 — Time & entities *(v0.6)* + +The "wow" queries. MemPalace's knowledge graph is already a dependency +— use it. + +- **`superton timeline [--days N]`** — chronological view of what + entered the palace: per-day sections, per-source drawer counts. +- **`superton digest [--days N]`** — a generated brief: "what you + worked on, decided, and left open," with citations. The + screenshot-able demo feature. Falls back to a non-model source + summary when no backend is available. +- **`superton about "person or project"`** — everything the palace + knows about one entity, aggregated across sources. +- **Temporal retrieval** — parse "last spring", "in March" in questions + and constrain retrieval by `created_at` before ranking. + +## Phase 3 — Trust & recall UX *(v0.7)* + +- **`superton open `** — jump from a citation to the full + drawer and its source file. Citations become actionable; that closes + the loop that makes people trust answers. +- **`superton recall`** — resurface aged drawers ("from 42 days ago") + — a second-brain feature no RAG competitor has. +- **Confidence surfacing** — a low-grounding banner instead of a + confidently thin answer. +- **Ingest breadth** — OCR fallback for image PDFs and screenshots; + Gemini CLI + Codex importers; browser bookmarks; `.mbox` email. +- **Plugin importers** via Python entry points so the community can add + sources without touching core. + +## Phase 4 — Sync & portability *(v0.8–0.9)* + +- **`superton sync`** — palace sync through the user's own remote (a + private git repo or any synced folder), built on the + `export`/`import-palace` JSONL round-trip. Optional symmetric + encryption. *Your memory follows you and still never touches our + servers.* +- **Palace merge semantics** — content-addressed ids make union-merge + safe by construction; conflicts cannot exist, only duplicates that + dedupe. + +## Phase 5 — The 1.0 headline + +- **`superton evolve`** — LoRA fine-tune from your drawers, so the + answer model gradually speaks in your voice. Ship last: it needs the + always-on pipeline (Phase 1) supplying fresh training data and sync + (Phase 4) to make the artifact portable. +- Hardening pass: crash-safe watcher state, palace integrity check + (`superton doctor --deep`), packaging polish. + +## What we explicitly will NOT do + +- **No web UI before 1.0.** It dilutes the CLI identity and doubles the + maintenance surface — the Textual TUI was removed for exactly this + reason. +- **No screen-recording / keylogging capture.** That is Rewind's lane; + the privacy blast radius conflicts with the local-first brand. +- **No cloud service of any kind.** Sync uses remotes the user already + controls. + +## Release mapping + +| Release | Contents | Why this order | +|---|---|---| +| v0.5 | `watch` + incremental refresh | Changes the product category | +| v0.6 | `timeline`, `digest`, `about`, temporal queries | The demo-able magic | +| v0.7 | `open` / `recall` / confidence + importers + OCR | Depth and trust | +| v0.8–0.9 | `sync`, plugin importers | Multi-machine story | +| v1.0 | `evolve` + hardening | The headline | + +## Sequencing rationale + +`watch` comes first because it multiplies the value of everything after +it: `digest` is only interesting if the palace is current, `recall` +only if it is deep, `evolve` only if it is both. Each phase lands as an +independent branch + PR so releases can ship the moment their phase +merges.