Product thesis v0: Sandnote is a resumability-first notebook for agents

[laotoutou]

Summary

This issue captures the current product conclusion for Sandnote after the exploratory discussion in #1.

The goal here is not to propose implementation details. It is to state the product thesis clearly enough to guide future design choices.

Product thesis

Sandnote is not agent memory. It is the agent's notebook.

Its core purpose is to preserve the continuity of thought.

A concise product promise is:

Come back to unfinished thought without starting over.

An even more operational v0 framing is:

Sandnote should help you stop without losing your place.

What Sandnote is

Sandnote is a CLI-first, filesystem-backed, headless notebook engine for agents.

It should be designed as an external thinking surface, not as a generic storage layer.

What Sandnote is not

Sandnote should not be defined as:

• a memory store
• a local database with a notebook veneer
• a full PKM suite
• a document editor first
• an AI wrapper that auto-generates understanding

Core model

A useful product model is:

• entry: a lightweight thinking unit
• thread: a continuable line of thought
• workspace: the current thinking surface that gives context
• topic surface: a durable re-entry surface for future work

These layers should stay distinct.

Main product stance

Sandnote should be:

• resumability-first, not storage-first
• thread-first in active work, not note-first
• context-aware, not container-first
• focused on re-entry value, not information volume

V0 center of gravity

If v0 must focus on one thing, it should focus on checkpoint quality.

The key question is not whether a session produced more text, but whether it left behind a better edge for future continuation.

A good checkpoint should minimally leave:

• a current stance
• an open edge
• a likely next lean
• a re-entry anchor

Lifecycle conclusion

Threads should have vitality states such as:

• live
• dormant
• settled

Promotion should remain a separate dimension from vitality.

• vitality answers whether a thread is still alive as a line of thought
• promotion answers whether some understanding is worth preserving as a durable topic-level re-entry point

Early product discipline

Sandnote should avoid drifting into:

• content management first
• structural completeness first
• long-lived knowledge accumulation first
• premature AI automation first

Instead, it should optimize for making interrupted thought easier to resume.

Why this matters

A notebook is not valuable because it stores everything.
A notebook is valuable because it lets thought survive interruption and become workable again.

That should remain the design center for Sandnote.

[laotoutou]

Use this issue's comments as the implementation-design thread that follows from the product thesis.

From this point on, implementation discussion should stay aligned with the thesis rather than reopening it.

Recommended order for implementation design:

1. define the v0 semantics clearly

   • entry
   • thread
   • workspace
   • topic surface
   • thread vitality: live, dormant, settled
   • checkpoint and edge semantics

2. define the v0 CLI surface

   • what the primary user-facing objects are
   • what the default entrypoint is
   • how capture, resume, checkpoint, and transition appear at the CLI layer

3. only then choose implementation details

   • repo layout
   • language/runtime
   • local storage layout
   • index/cache strategy
   • optional LLM integration points

A useful constraint for follow-up design work:

• do not start from storage
• do not start from database abstractions
• do not start from editor features
• start from resumability, checkpoint quality, and thread-first work

[laotoutou]

Implementation-design continuation: a first pass at the canonical CLI surface.

The goal here is semantic clarity first, not command minimization.

A useful v0 canonical surface is:

sandnote entry ...
sandnote thread ...
sandnote workspace ...
sandnote topic ...
sandnote repl

1. entry

entry is the lightweight thinking-unit layer.

Likely actions:

• sandnote entry create
• sandnote entry show <id>
• sandnote entry list
• sandnote entry revise <id>
• sandnote entry link <id>
• sandnote entry attach <id>
• sandnote entry archive <id>

The important boundary is that entry should stay lightweight. It should not carry thread continuity on its own.

2. thread

thread is the primary working layer.

Likely actions:

• sandnote thread create
• sandnote thread show <id>
• sandnote thread list
• sandnote thread resume <id>
• sandnote thread inspect <id>
• sandnote thread checkpoint <id>
• sandnote thread transition <id> --to <state>
• sandnote thread entries <id>
• sandnote thread attach <id> <entry-id>
• sandnote thread detach <id> <entry-id>

This layer is the design center. The key actions are not CRUD, but resume, checkpoint, and transition.

3. workspace

workspace is the current thinking surface that gives context.

Likely actions:

• sandnote workspace create
• sandnote workspace show <id>
• sandnote workspace list
• sandnote workspace use <id>
• sandnote workspace threads <id>
• sandnote workspace focus <id> <thread-id>
• sandnote workspace attach <id>
• sandnote workspace detach <id>

workspace should not be treated as a directory substitute. Its role is to provide current relevance and current context.

4. topic

topic is the durable re-entry layer.

Likely actions:

• sandnote topic create
• sandnote topic show <id>
• sandnote topic list
• sandnote topic orient <id>
• sandnote topic promote <id>
• sandnote topic entries <id>
• sandnote topic threads <id>

topic should not be treated as the final state of every thread. It is a layer for durable re-entry surfaces.

5. repl

repl should be a first-class interface, not just a shortcut shell.

Its purpose is to support continuous thought work over an explicit notebook state.

A useful minimum REPL session state is:

• current_workspace
• focus_thread
• inspection_scope
• pending_checkpoint_context

The REPL should feel like a working console for one workspace and one active thread at a time.

Interface constraint

REPL shortcuts should always map back to canonical CLI forms. The stateful interface may reduce friction, but it should not invent a separate semantic model.

Output constraint

Canonical commands should support stable machine-readable output, such as --json, in addition to concise human-readable output.

[laotoutou]

Implementation-design continuation: tighten the semantic boundaries of the thread loop.

The most important v0 command boundaries are likely these four:

• thread resume
• thread inspect
• thread checkpoint
• thread transition

They should not collapse into one another.

thread resume

Purpose: restore the minimum useful surface needed to continue a thread.

This should answer, at minimum:

• what the thread is about
• what the current working belief is
• what remains open
• where thought most naturally leans next
• what to re-enter through

resume is not a full history view. It is the default re-entry surface for active thought.

thread inspect

Purpose: examine the thread's current state more deeply than resume.

This should allow the caller to look at:

• supporting entries
• related context
• belief and edge in more detail
• nearby threads or local structure when relevant

inspect is exploratory. resume is restorative.

thread checkpoint

Purpose: leave behind a better edge than the one the current session resumed from.

A good checkpoint should minimally leave:

• a current stance
• an open edge
• a likely next lean
• a re-entry anchor

checkpoint should not be treated as generic editing. It is the core action for preserving continuity across interruption.

thread transition

Purpose: change the thread's vitality state honestly.

This should primarily answer whether the thread is now:

• live
• dormant
• settled

This is distinct from promotion. Promotion is about durable topic-level re-entry value, not thread vitality.

Boundary summary

A compact way to distinguish the four commands is:

• resume: help me continue
• inspect: help me see more clearly
• checkpoint: help me leave a better stopping point
• transition: help me state what life this thread is now in

This command quartet is likely the dynamic center of Sandnote.

[laotoutou]

Final implementation direction for v0.

At this point the product discussion is stable enough to stop expanding concepts and start implementing against a fixed semantic surface.

1. Canonical CLI surface

Keep the canonical CLI explicit and object-based:

sandnote entry ...
sandnote thread ...
sandnote workspace ...
sandnote topic ...
sandnote repl

Object roles:

• entry: lightweight thinking unit
• thread: primary working unit
• workspace: current thinking context
• topic: durable re-entry surface
• repl: stateful working console over explicit notebook state

2. Thread is the design center

thread is the main working layer for v0.

A useful canonical command set is:

• sandnote thread create
• sandnote thread show <id>
• sandnote thread list
• sandnote thread resume <id>
• sandnote thread inspect <id>
• sandnote thread checkpoint <id>
• sandnote thread transition <id> --to <state>
• sandnote thread entries <id>
• sandnote thread attach <id> <entry-id>
• sandnote thread detach <id> <entry-id>

The key actions are not CRUD. They are resume, checkpoint, and transition.

3. Command boundaries

These commands should stay distinct:

thread show

Canonical object overview.

Should answer at a high level:

• what the thread is
• what vitality state it is in
• what its current belief and edge are
• what workspace or topic context it belongs to

thread resume

Minimum continuation surface.

Should answer:

• what this thread is about
• what is currently believed
• what remains open
• where thought leans next
• what to re-enter through

This is the default working re-entry view.

thread inspect

Deeper exploratory view.

Should allow expansion into:

• supporting entries
• related context
• nearby structure
• more detail around belief and edge

thread checkpoint

Continuity-preserving write action.

A good checkpoint should minimally leave:

• a current stance
• an open edge
• a likely next lean
• a re-entry anchor

This is not generic editing. It is the core action for leaving behind a better stopping point.

thread transition

Vitality-state change.

Primarily for changing the thread to:

• live
• dormant
• settled

This stays separate from promotion.

4. REPL role

repl should be a first-class interface, not a shortcut shell.

Useful minimum session state:

• current_workspace
• focus_thread
• inspection_scope
• pending_checkpoint_context

REPL shortcuts must map back to canonical CLI forms. The stateful interface should reduce friction without creating a second semantic model.

5. Output requirement

Canonical commands should support both:

• concise human-readable output
• stable machine-readable output such as --json

6. Implementation order

A reasonable implementation order from here is:

1. implement the core thread model and vitality states
2. implement canonical thread commands first
3. implement entry as lightweight support material
4. implement workspace context handling
5. implement repl on top of the canonical command model
6. leave topic promotion and optional LLM assistance until the thread loop is solid

This is enough to start implementation. The semantics and CLI direction are now clear enough.

[laotoutou]

Implementation research summary and recommendation.

Recommended v0 stack

Language: Go

Recommendation: implement v0 in Go.

Why:

• it matches the surrounding workspace and existing engineering stack
• static binaries are a good fit for a CLI-first tool
• the repo already lives next to a Go-heavy codebase
• Go is strong enough for structured CLI, file-backed state, and PTY/REPL integration without adding runtime complexity

Canonical CLI: Cobra

Recommendation: use Cobra for the canonical CLI.

Why:

• its model is explicitly subcommand-based, which fits the object surface we already settled on
• it gives stable help, suggestions, nested subcommands, and generated shell completion
• it is the right level of boring for the canonical interface

REPL: line-oriented, not TUI-first

Recommendation: do not start with Bubble Tea as the main interaction model.

Reason:

• Bubble Tea is a full TUI framework and is better suited to terminal applications with richer screen state
• for Sandnote v0, the main need is a stateful working console over explicit notebook state, not a full-screen TUI that risks introducing a second semantic model

Recommendation for the first REPL implementation:

• prefer a line-oriented REPL library such as github.com/nao1215/prompt
• keep the REPL mapped directly onto canonical commands and explicit session state

The REPL should primarily hold:

• current workspace
• focus thread
• inspection scope
• pending checkpoint context

Recommended storage direction for v0

Recommendation: keep the filesystem as the only source of truth for v0.

Use a repository-style local layout with object files for authoritative state and keep any index/cache derived and rebuildable.

Suggested direction:

• entries/ for lightweight thinking units
• threads/ for thread continuity state
• workspaces/ for context state
• topics/ for durable re-entry surfaces
• index/ or equivalent only as derived state later, not as authority

For v0, it is better to prefer explicit object files over introducing an embedded database too early.

Important implementation constraint

Do not start by designing an internal database abstraction.

Start by implementing:

1. thread vitality state
2. canonical thread commands
3. checkpoint write path
4. REPL session state on top of canonical commands

Only after the thread loop is solid should Sandnote add:

• topic promotion flow
• derived index/cache
• optional LLM-assisted operations

Concrete next step

The next practical step is to scaffold a Go CLI with:

• Cobra command tree
• a minimal file-backed object store
• thread-first commands: show, resume, inspect, checkpoint, transition
• a line-oriented REPL that reuses the same command semantics