Using the Scratchpad

The Problem¶

During a session you accumulate quick notes, reminders, intermediate values, and sometimes sensitive tokens. They don't fit TASKS.md (not work items) or DECISIONS.md (not decisions). They don't have the structured fields that LEARNINGS.md requires.

Without somewhere to put them, they get lost between sessions.

How do you capture working memory that persists across sessions without polluting your structured context files?

TL;DR¶

ctx pad add "check DNS propagation after deploy"
ctx pad         # list entries
ctx pad show 1  # print entry (pipe-friendly)

Entries are encrypted at rest and travel with git.

Use the /ctx-pad skill to manage entries from inside your AI session.

Commands and Skills Used¶

The Workflow¶

Step 1: Add a Note Naturally¶

You don't need to remember any syntax. Just tell your assistant what to jot down:

You: "jot down: check DNS propagation after deploy"

Agent: "Added to scratchpad:
  1. check DNS propagation after deploy"

Behind the scenes, the agent runs ctx pad add "check DNS propagation after deploy".

Step 2: View Your Scratchpad¶

You: "show my scratchpad"

Agent: "Your scratchpad has 3 entries:
  1. check DNS propagation after deploy
  2. staging API endpoint: api.staging.example.com/v2
  3. retry limit should be 5, not 3"

Step 3: Edit an Entry¶

You: "update entry 2 to include the new endpoint"

Agent: "Updated entry 2:
  was: staging API endpoint: api.staging.example.com/v2
  now: staging API endpoint: api.prod.example.com/v2"

For partial edits, the agent can use --append or --prepend:

You: "append the port number to entry 2"

Agent: "Updated entry 2:
  staging API endpoint: api.prod.example.com/v2 :8443"

Step 4: Compose Entries¶

Use ctx pad show N to pipe entry content into other operations:

You: "append the content of entry 3 to entry 1"

Agent: [runs ctx pad edit 1 --append "$(ctx pad show 3)"]
       "Done. Entry 1 is now:
        check DNS propagation after deploy retry limit should be 5, not 3"

Step 5: Reorder by Priority¶

You: "move entry 4 to the top"

Agent: [runs ctx pad mv 4 1]
       "Moved entry 4 to position 1. Scratchpad reordered."

Step 6: Clean Up¶

You: "remove entry 2, it's done"

Agent: [runs ctx pad rm 2]
       "Removed entry 2. 3 entries remaining."

Step 7: Store a File as a Blob¶

The scratchpad can hold small files (up to 64 KB) as encrypted blob entries. The file is base64-encoded and stored alongside a label you provide:

# Ingest a file: the first argument is the label
ctx pad add "deploy config" --file ./deploy.yaml

# List shows the label with a [BLOB] marker
ctx pad
#   1. check DNS propagation after deploy
#   2. deploy config [BLOB]

Step 8: Extract a Blob¶

Use show --out to write the decoded file back to disk:

# Write blob entry to a file
ctx pad show 2 --out ./recovered-deploy.yaml

# Or print to stdout (for piping)
ctx pad show 2 | head -5

Blob entries are encrypted identically to text entries: They're just base64-encoded before encryption. The --out flag decodes and writes the raw bytes.

Step 9: Bulk Import Notes¶

When you have a file with many notes (one per line), import them in bulk instead of adding one at a time:

# Import from a file: Each non-empty line becomes an entry
ctx pad import notes.txt

# Or pipe from stdin
grep TODO *.go | ctx pad import -

All entries are written in a single encrypt/write cycle, regardless of how many lines the file contains.

Step 10: Export Blobs to Disk¶

Export all blob entries to a directory as individual files. Each blob's label becomes the filename:

# Export to a directory (created if needed)
ctx pad export ./ideas

# Preview what would be exported
ctx pad export --dry-run ./ideas

# Force overwrite existing files
ctx pad export --force ./backup

When a file already exists, a unix timestamp is prepended to the filename to avoid collisions. Use --force to overwrite instead.

Using /ctx-pad in a Session¶

Invoke the /ctx-pad skill first, then describe what you want in natural language. Without the skill prefix, the agent may route your request to TASKS.md or another context file instead of the scratchpad.

You: /ctx-pad jot down: check DNS after deploy
You: /ctx-pad show my scratchpad
You: /ctx-pad delete entry 3

Once the skill is active, it translates intent into commands:

When to Use Scratchpad vs Context Files¶

Decision Guide

• If it has structured fields (context, rationale, lesson, application), it belongs in a context file like DECISIONS.md or LEARNINGS.md.
• If it's a work item you'll mark done, it belongs in TASKS.md.
• If you want a message relayed VERBATIM at the next session start, it belongs in ctx remind.
• If it's a quick note, reminder, or working value (especially if it's sensitive or ephemeral) it belongs on the scratchpad.

Tips¶

• Entries persist across sessions: The scratchpad is committed (encrypted) to git, so entries survive session boundaries. Pick up where you left off.
• Entries are numbered and reorderable: Use ctx pad mv to put high-priority items at the top.
• ctx pad show N enables unix piping: Output raw entry text with no numbering prefix. Compose with --append, --prepend, or other shell tools.
• Never mention the key file contents to the AI: The agent knows how to use ctx pad commands but should never read or print the encryption key (~/.ctx/.ctx.key) directly.
• Encryption is transparent: You interact with plaintext; the encryption/decryption happens automatically on every read/write.

Next Up¶

Syncing Scratchpad Notes Across Machines →: Distribute encryption keys and scratchpad data across environments.

See Also¶

• Scratchpad: feature overview, all commands, encryption details, plaintext override
• Persisting Decisions, Learnings, and Conventions: for structured knowledge that outlives the scratchpad
• The Complete Session: full session lifecycle showing how the scratchpad fits into the broader workflow