Scratchpads and todos as agent memory

Scratchpads and todos give Solo agents a project memory layer that survives chat history, agent restarts, and handoffs. Treat them as tools you can ask your agents to maintain: scratchpads hold durable Markdown context, while todos track concrete work with status, priority, blockers, comments, and coordination locks.

Ask the agent to build the memory layer#

For tasks with substantial context, start by asking an agent to create the memory structure before it edits files.

Useful prompts:

• Create a scratchpad for this investigation, interview me for missing context, and keep it updated as the source of truth.
• Read this research, import or summarize it into a scratchpad, then extract todos with blockers and priorities.
• Before implementation, create a scratchpad plan and convert it into Solo todos for agents to work from.
• Keep todos and scratchpads current as you work. Do not rely on chat scrollback for handoff context.

The goal is not for you to manually curate every note. The goal is to tell the agent what memory you need, then have it create and maintain the scratchpad and todo records through Solo MCP.

Use scratchpads for context#

Ask agents to use scratchpads when the information is reference material: investigation notes, assumptions, links, command output worth keeping, design decisions, reproduction steps, API quirks, imported research, or a handoff narrative for the next worker.

A useful scratchpad has headings that future agents can scan:

• Goal
• Current understanding
• Source notes
• Relevant files and commands
• Decisions
• Open questions
• Next actions

Headings matter because agents can read a whole scratchpad, a headings-only outline, or a specific section. A well-shaped scratchpad lets a later worker jump straight to the relevant context instead of rereading a long chat.

Import or summarize external research#

If you have deep research from the web, a long issue, a design doc, or a transcript, give it to the agent and ask it to turn that material into project memory.

Useful prompts:

• Import this research into a scratchpad. Preserve links and source notes, then write a short summary at the top.
• Read this deep research and extract implementation assumptions, risks, and open questions into a scratchpad.
• Create todos from this research. Use blockers where one task depends on another, and link each todo back to the scratchpad section it came from.

If the source is a local file, ask the agent to load it into a scratchpad. If it is a web page or pasted research, ask the agent to preserve links, dates, and caveats so the next agent knows where the context came from.

Use todos for work#

Ask agents to create todos when the information is work to be done: a fix, follow-up, review item, migration step, investigation, or blocked task that needs ownership, status, priority, or completion tracking.

For each todo, have the agent include:

• The concrete objective.
• The owner or intended worker lane.
• The related scratchpad link or heading.
• Acceptance checks.
• Priority and tags.
• Blockers, if another todo must finish first.

Todos should not duplicate the whole scratchpad. They should point to the durable context and describe the next action clearly enough that an agent can pick up the work.

Have agents set blockers#

Blockers turn a flat task list into an orchestration plan. Ask the agent to mark dependencies explicitly instead of leaving them implied in prose.

Useful prompts:

• Set blockers so implementation todos must finish before verification todos.
• Block the integration todo on all worker-lane todos.
• When a worker finishes, update the dependent todos and unblock the next lane if it is ready.

Blocker relationships are project-scoped. If a todo is moved to another project, Solo preserves comments and completion state but clears blockers and locks because those relationships belong to the source project.

Use comments for handoffs#

Ask agents to put short, task-specific updates in todo comments. Comments stay attached to the task activity timeline and are better than editing a long scratchpad for every small status update.

Useful comment prompts:

• Leave a todo comment with what changed, files touched, tests run, and remaining risk.
• Comment on the blocked todo with exactly what is missing.
• When you hand off, add a final comment that the next agent can act on without reading the full chat.

Use scratchpads for broad context and todos/comments for the work trail. The next worker should be able to read the scratchpad for background, then read the todo comments for recent activity.

Let agents coordinate with locks#

Todo locks are coordination signals. Ask agents to lock a todo while actively editing or reviewing it, and unlock it when the handoff is captured.

Useful prompts:

• Lock the todo you are actively working on and release it when your handoff is written.
• Before editing a locked todo, inspect who owns the lock and whether it is stale.
• If you spawn workers, have each worker lock only the todo it owns.

Solo renews UI locks while a todo detail view is open, and process-owned MCP locks are released when the bound process closes. A lock is not permanent ownership; it is a signal to avoid overlapping work.

Keep scratchpads and todos synchronized#

Ask the agent to keep the scratchpad and todos in sync as work changes. The scratchpad should explain the plan and durable context. The todos should show what is actually actionable.

Useful prompts:

• Reconcile the scratchpad with the current todo state before dispatching more work.
• Update the scratchpad summary, then mark todo statuses honestly: open, in progress, backlog, or completed. Represent blocked work with blocker relationships on an open todo.
• If new context changes the plan, update the scratchpad and add todo comments explaining the change.

For long-running work, end each session with three updates: refresh the scratchpad summary, mark todo statuses honestly, and leave a final comment on any todo that another person or agent may pick up.

Agent-visible tools#

Solo exposes scratchpads and todos through its existing MCP server when those tools are enabled in settings. The Scratchpads and Todos cards in settings show the exact tool names that will be exposed. These toggles augment the existing MCP server; they do not start a separate server.

Scratchpad tools let agents list, read, create, replace, rename, tag, append, clear, delete, archive, transfer, import, and export project scratchpads. Scratchpad writes use revision guards, so an agent should read the current revision before replacing content and handle revision conflicts instead of overwriting newer edits.

Todo tools let agents create, list, read, update, tag, transfer, set blockers, complete, lock, unlock, delete, and comment on project todos. Agents can also list todo comments and distinct tags. UI changes and agent changes use the same project-scoped records, so work done in either place appears in the other.

A practical agent-first loop#

Use this loop when a task needs durable memory:

1. Ask the lead agent to interview you for context.
2. Have it create or import a scratchpad.
3. Have it extract todos, priorities, tags, and blockers.
4. Have it dispatch workers for unblocked todos.
5. Have workers lock their todos, update comments, and report handoffs.
6. Have the lead agent update the scratchpad summary and unblock the next work.
7. Complete todos only after the result is verified.

Do not rely on chat scrollback for anything the next session must know. Put durable facts in a scratchpad and actionable next steps in todos.