cameron.stream / note
[READ-ONLY] Mirror of https://github.com/just-cameron/note. External storage tool for Letta agents to manage persistent notes
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

Go 50.5%
Python 28.3%
HTML 16.5%
Shell 3.3%
Makefile 1.4%
Other 0.1%
9 3 0

Clone this repository

https://git.vm.fail/cameron.stream/note https://git.vm.fail/did:plc:j3a7ypiugdazlwnpdpc5lyqz
ssh://git@knot1.tangled.sh:2222/cameron.stream/note ssh://git@knot1.tangled.sh:2222/did:plc:j3a7ypiugdazlwnpdpc5lyqz

For self-hosted knots, clone URLs may differ based on your setup.


Download tar.gz Download .zip
README.md

Letta Note#

A custom tool that gives Letta agents a file system for their memory blocks.

Agents can store an arbitrary number of notes, organized into folders, and selectively attach them to their context window when needed. This enables progressive disclosure: instead of loading everything at once, agents mount only what's relevant to the current task.

Notes persist in your Letta server and can be viewed, edited, searched, and reorganized on demand.

Installation#

WARNING: Custom tools in Letta are not versioned. If you overwrite an existing tool called note with this one, you may not be able to restore your original tool.

curl -sSL https://raw.githubusercontent.com/cpfiffer/note/main/install.sh | bash

The installer will prompt for your API key (or use LETTA_API_KEY if set) and attach the tool to your agent via ADE or SDK.

It will check to see if a tool of the same name exists and confirm whether you want to overwrite it.

Usage#

note(command="attach", path="/tasks", content="TODO: Review code")
note(command="view", path="/tasks")
note(command="list")

Commands#

  • create - Create a new note (not attached to context)
  • view - Read note contents
  • attach - Load note into agent context (creates if missing)
  • detach - Remove from context (keeps in storage)
  • insert - Insert content at a specific line
  • append - Add content to end of note
  • replace - Find and replace text
  • rename - Move/rename note
  • copy - Duplicate note
  • delete - Permanently remove note
  • list - List notes by path prefix
  • search - Search notes by label or content
  • attached - Show currently attached notes

Practical Usage Patterns#

Attach/Detach for Context Management:

note attach /reference/api-docs    # Load into context when needed
note detach /reference/api-docs    # Remove when done to free context space

Bulk Operations:

note attach /folder/*              # Attach all notes in a folder
note detach /folder/*              # Detach all

Progressive Disclosure:

  • Keep detailed references in notes, only attach when relevant
  • Detach after use to keep context window lean
  • Use note attached to see what's currently loaded

Organizational Patterns:

/projects/          # Project-specific notes
/references/        # Documentation, API specs
/learning/          # Curriculum, lesson plans
/shared/            # Cross-agent shared content

Note Directory#

A /note_directory block is automatically maintained and attached to your agent. It displays all notes in a tree view with the first 80 characters of each note's first line as a preview.

Write descriptive first lines - they serve as the summary in your directory listing.

Tips#

  1. Notes are blocks - each note is a memory block with a path-like label, scoped to your agent
  2. Attach = load into context - attaching a note adds it to your agent's active memory blocks
  3. Detach ≠ delete - detaching removes from context but the note still exists in storage
  4. Folders are also notes - /projects and /projects/task1 can both have content
  5. Use descriptive paths - the label is your only way to find notes later

Command Permissions#

By default, all commands are enabled. You can restrict which commands are available by setting the ENABLED_COMMANDS environment variable on your Letta server:

# Enable all commands (default)
ENABLED_COMMANDS="all"

# Disable delete (safer for production)
ENABLED_COMMANDS="create,view,attach,detach,insert,append,replace,rename,copy,list,search,attached"

# Read-only mode
ENABLED_COMMANDS="view,list,search,attached"

Disabled commands will return an error message listing which commands are enabled.

note-sync CLI#

A standalone CLI tool for syncing notes between Letta and your local filesystem. Think Obsidian for Letta notes.

Installation#

# Build from source
go build -o note-sync ./cmd/note-sync

# Or install directly
go install github.com/cpfiffer/note/cmd/note-sync@latest

Requires LETTA_API_KEY environment variable.

Commands#

# List your agents
note-sync agents
note-sync agents --name cameron    # Search by name

# Initialize a sync directory
note-sync init <agent_id>
note-sync init <agent_id> --dir ~/my-notes

# Sync notes
note-sync pull                     # Download from Letta
note-sync push                     # Upload to Letta
note-sync status                   # Show what's changed

# Web UI
note-sync serve                    # Start web UI at localhost:8080
note-sync serve --port 3000

File Mapping#

Notes map to local markdown files:

/projects/webapp  →  projects/webapp.md
/todo             →  todo.md

Conflict Handling#

When both local and remote have changed, pull creates .conflict.md files so you don't lose data. Resolve manually, then push.

Web UI#

note-sync serve starts a local web server with:

  • Agent selection with search
  • Note browser sidebar
  • Rich text editor (Tiptap) with markdown round-trip
  • Save directly to Letta