Define the core requirements of an agent notebook

[laotoutou]

Summary

Sandnote should be designed around the question: why do humans need notebooks at all?

This issue captures the core product requirements for an agent notebook from that perspective. These are requirements, not implementation decisions.

Problem

It is easy to reduce a notebook to storage, file management, or a thin wrapper over Markdown. That misses the real reason notebooks exist.

A notebook is not just a place to save text. It is an external surface for thought.

If Sandnote is meant to be the notebook for agents, it should be defined by the cognitive jobs a notebook performs, not by file formats, indexing strategies, or specific command designs.

Requirements

1. Capture

A notebook must make it cheap to capture thoughts, fragments, observations, and partial conclusions before they are lost.

2. Hold

A notebook must reduce working-memory pressure by holding unfinished ideas, intermediate states, and things that need to be resumed later.

3. Restructure

A notebook must support reshaping thought: reorganizing, revising, splitting, combining, and refining material into clearer forms.

4. Compare

A notebook must support comparison across versions, alternatives, evidence, and conclusions so that thought can be examined rather than merely recorded.

5. Recall

A notebook must make prior material retrievable in context, not only by exact file path or title, but by meaning, task, relationship, and relevance.

6. Continue

A notebook must support continuity across time, so work can be resumed, extended, and carried forward without restarting from scratch.

Non-goals

This issue does not propose:

• a storage format
• a filesystem layout
• a CLI design
• an indexing implementation
• a history or revision implementation
• a memory model

Those should be derived later from the requirements above.

Expected outcome

Future design work for Sandnote should be evaluated against these six requirements first:

• capture
• hold
• restructure
• compare
• recall
• continue

A feature that does not strengthen one or more of these requirements is likely not central to the notebook itself.

[laotoutou]

Follow-up product framing from later discussion.

A useful clarification is that notebook and memory should be treated as peer systems, not as parent/child layers or thin wrappers around one another.

• memory preserves what happened
• a notebook supports what thinking becomes

That distinction matters because Sandnote should not be defined as another memory store. Its role is the agent's external thinking workspace.

A second clarification is about the product's semantic center.

Sandnote should probably not be designed around files as the primary object, even if files remain the source of truth underneath. The notebook should be designed around thinking units and work continuity.

Current working model:

• note should be closer to a card than to a document or a block
• workspace should mean the current task's working set, not UI tab state
• link should be treated as a first-class relationship, not just parsed syntax
• revision should be treated as a first-class semantic concept, not only file history

Why this framing seems useful against the six requirements:

• capture benefits from small, independent cards
• hold and continue need a workspace concept
• restructure depends on cards, links, and revisions
• compare depends on revisions and explicit relationships
• recall depends on links, context, and structure, not just paths or full-text search

This still avoids implementation choices, but it gives future design work a clearer semantic direction: Sandnote should be notebook-first, not file-first.

[laotoutou]

Another product-level clarification from later discussion.

The notebook should be understood as a place where thought becomes workable over time, not merely where text is stored. That suggests a content lifecycle rather than a flat collection of files.

A useful conceptual lifecycle for notebook content may be:

• fragment: a raw observation, question, hint, or partial thought
• card: a small, independent thinking unit that can stand on its own
• working set: the currently active set of cards for a task or line of thought
• refined note: a more deliberate and organized expression
• durable reference: a stable note worth returning to repeatedly

This is still not an implementation model. It is a way to reason about how notebook content matures.

Another clarification: LLM support should be optional.

Sandnote should remain a complete notebook without any LLM dependency. LLMs may assist notebook work, but they should not define notebook truth.

At the product level, that implies:

• Sandnote must remain fully usable without an LLM
• any LLM integration should be additive rather than foundational
• LLMs can help shape notes, but should not be the authority for identity, revision, history, or persistence

A concise way to frame this is:

• the notebook is the workspace
• the filesystem is the durable substrate
• LLMs are optional assistants

This seems aligned with the earlier requirements for capture, hold, restructure, compare, recall, and continue.

[laotoutou]

Another useful boundary from later discussion.

Sandnote should probably not try to catch every unfinished thing. That would turn it into a generic dumping ground.

A better boundary is:

A thing belongs in the notebook when it is unfinished, but worth continuing.

This helps distinguish notebook material from raw traces or generic memory.

Examples of notebook-worthy unfinished thought:

• open questions worth returning to
• working hypotheses that still need validation
• partial syntheses that are not yet stable
• task-shaped materials that need more work
• emerging references that may later become durable knowledge

By contrast, many things are unfinished but still do not belong in the notebook:

• one-off command output
• ephemeral intermediate results
• material that can be trivially recomputed
• traces with no expected follow-up value

This gives a clearer product boundary between memory and notebook:

• memory asks whether something happened and whether that trace should be preserved
• the notebook asks whether something is worth revisiting, restructuring, or building on

That distinction also sharpens the role of Sandnote itself: it should be the place where unfinished thought that matters can be resumed and developed, not a generic storage layer.

[laotoutou]

A further reduction from the resumption discussion.

A notebook does not need to preserve every detail of the thinking process. What it must preserve is the minimum state required to make unfinished thought resumable.

That suggests a smaller core than a full process log.

At the product level, the notebook likely must preserve at least:

• whether something is still open
• the current working belief or provisional understanding
• why the thread matters enough to resume
• where thinking stopped
• what related material helps re-enter the thread

This can be viewed as the minimum resumable state.

A useful test for Sandnote is whether, after interruption, it can help answer these five questions:

1. What have I not finished thinking through?
2. What did I already believe last time?
3. Why does this matter?
4. Where did I stop?
5. What related material should I re-enter through?

If Sandnote can answer these reliably, it is much closer to being a real notebook rather than just a searchable note store.

[laotoutou]

Another reduction from the workspace discussion.

A useful distinction is that workspaces likely come in two different shapes:

• task-shaped workspaces for active work, interruption, and resumption
• topic-shaped workspaces for longer-lived understanding and reuse

Both seem necessary, but task-shaped workspaces should probably be the default center of gravity for an agent notebook.

Why task-shaped should be primary:

• interruption happens in tasks
• resumption happens in tasks
• next-step pressure happens in tasks
• "what is still open" is usually task-shaped

Why topic-shaped still matters:

• some understanding outlives any single task
• durable references form around systems, concepts, and recurring problem areas
• future tasks need a stable thematic surface to re-enter through

This suggests Sandnote should not treat a workspace as just a folder or collection. A workspace is better understood as a current thinking surface over entries.

A compact framing is:

• task work creates pressure
• the notebook captures and resumes that pressure
• stable parts of that work migrate into topic understanding
• future task work re-enters through that topic surface

[laotoutou]

Another important reduction from the promotion discussion.

Promotion should not mean moving anything useful from task work into the long-lived layer. That would quickly pollute topic-level understanding.

A useful boundary is that content should not be promoted when its value still depends mostly on the current task context.

Examples of content that likely should not be promoted directly:

• raw task residue
• unfiltered hypotheses
• context-bound decisions
• procedural clutter
• premature summaries that look stable but are not

This sharpens the distinction between the two workspace shapes:

• task workspaces hold action value and local continuity value
• topic workspaces should hold re-entry value and structural value

That suggests promotion is not just refinement. It is also filtering under future-use pressure.

In other words, topic workspaces should not aim to collect everything that was useful once. They should aim to preserve material that is worth re-entering across tasks.

[laotoutou]

Another useful reduction from the entry discussion.

Task entries and topic entries likely should not be treated as two unrelated object types. A better model is that they share one common semantic core, but emphasize different aspects in different workspace shapes.

A plausible common semantic core for any thinking entry is:

• what it is about
• what state it is currently in
• what it currently means
• what surrounding context it connects to

On top of that shared core, task-shaped work emphasizes:

• what is still pressing
• where work should continue
• why this matters now

And topic-shaped work emphasizes:

• how this helps orient future work
• what this explains or bounds
• why this is a good future re-entry point

This suggests Sandnote may not need two separate note systems. It may need one shared thinking-entry model, used under two different workspace emphases: continuation in task work, and re-entry in topic work.

[laotoutou]

Another useful reduction from the resumption discussion: the missing middle layer is likely a thread.

A thread is not a file, not a single note, and not an entire workspace. It is an open line of thought.

A useful framing is:

• entries are thinking units
• threads are resumable lines of thought supported by entries
• workspaces are the current thinking surfaces in which one or more threads matter

This helps explain what is actually resumed after interruption. In many cases, what resumes is not a note and not a whole workspace, but a particular thread.

A plausible semantic minimum for a thread is:

• the question or tension it is organized around
• the current working belief
• the open edge
• the supporting entries
• why it matters in the current workspace

This suggests that Sandnote's dynamic center may be thread-first rather than note-first.

[laotoutou]

Another clarification from the thread discussion.

A thread should probably not be treated as an upgraded form of a single entry. A better model is that a thread is an independent line of continuable thought, while one or more entries may serve as its early anchors.

That helps preserve the distinction between:

• entries as local thinking units
• threads as continuable lines across context

This also leaves room for two different ways a thread can appear:

• it may be seeded by a strong single entry
• it may emerge across multiple entries as unresolved tension accumulates

Under that framing, a seed entry is not "the thread itself". It is better understood as an anchor of emergence: a place where the line of thought first became visible.

This matters because future re-entry points can shift over time:

• early on, re-entry may happen through a seed entry
• during active work, re-entry may happen through the live thread
• after promotion, re-entry may happen through a topic-level entry point

That suggests Sandnote should preserve the distinction between local thought, continuable thought, and durable re-entry surfaces rather than collapsing them into one object.

[laotoutou]

Another useful reduction from the thread loop discussion.

If the thread loop is roughly:

• resume
• inspect
• advance
• checkpoint
• transition

then Sandnote should not support all of these equally.

A strong product stance is:

• support resume strongly
• support checkpoint strongly
• support transition strongly
• keep advance light
• treat inspect as a middle case

Why this matters:

• resume is one of the main reasons the notebook exists at all
• checkpoint is what turns current work into future resumability
• transition prevents every thread from staying artificially live forever
• advance is the inside of thought itself, and should not be over-structured

A compact framing is:

Sandnote should support the boundaries of thought strongly, and the inside of thought lightly.

That seems more faithful to what a notebook is: not a machine that thinks for you, but a surface that helps thought start, continue, pause, and resume well.

[laotoutou]

A current reduction of the discussion into product principles.

Possible Sandnote product principles v0:

1. Resumability first
   Sandnote should optimize for helping interrupted thought continue, not for storing everything.

2. Notebook, not memory
   Memory preserves what happened. Sandnote should preserve how thought can continue.

3. Thread-first work
   The primary working unit should be the thread, since threads are what get resumed, advanced, suspended, and revisited.

4. Entries stay lightweight
   Entries should remain small thinking units and support capture, local meaning, and linking, rather than trying to carry full continuity on their own.

5. Workspaces give context
   A workspace should provide current relevance and thinking context, not just act as a container.

6. Promote for re-entry, not for cleanliness
   Promotion should preserve future re-entry value, not simply move useful material into a tidier long-lived layer.

7. Support the boundaries of thought
   Sandnote should support resume, checkpoint, and transition strongly, while keeping the inside of thought relatively unconstrained.

A shorter version of these principles might be:

• resumability over storage
• threads over notes
• context over containers
• re-entry value over information volume

[laotoutou]

Another useful reduction: what Sandnote should avoid doing first.

Sandnote should not begin by trying to become a better knowledge base, a better document editor, or a smarter AI wrapper.

The highest-risk early drifts seem to be:

• trying to recreate a full PKM or note-management suite too early
• optimizing for heavy document workflows
• reducing the problem back into database design in disguise
• over-automating summarization, promotion, or thread creation with LLMs
• turning every entry into a thread
• promoting too much task-local material into long-lived topic surfaces
• forcing rigid workflows that over-structure capture and advance

A compact framing is:

• do not optimize for managing content first
• do not optimize for auto-generating understanding first
• do not optimize for structural completeness first

Instead, optimize for making interrupted thought easier to resume.

[laotoutou]

Another useful reduction from the edge discussion.

A checkpoint does not need to produce a full summary. It only needs to leave behind the minimum state required for low-cost re-entry.

A plausible minimum checkpoint output is:

• current stance: where the thread currently stands
• open edge: what remains unresolved
• next lean: where thought most naturally wants to continue
• re-entry anchor: what future work should re-enter through

In other words, a checkpoint is good when it leaves:

• a clear current position
• a live opening
• a likely next lean
• a minimal context anchor

This keeps the checkpoint focused on resumability rather than on producing polished summaries.

[laotoutou]

Another useful reduction from the transition discussion.

Transition should first clarify a thread's vitality state, not its relationship to topic surfaces.

That suggests two different dimensions should stay separate:

1. vitality transition

• live
• dormant
• settled

2. promotion transition

• whether some part of the thread has become worth preserving as a durable re-entry point

This matters because promotion is not the destiny of every thread, and topic surfaces should not be treated as the final state of thread life.

A better framing is:

• threads have vitality states
• topic surfaces have re-entry roles
• promotion links the two, but should not collapse them into one lifecycle