Tools Reference

EchOS is an agent, not a command-line app. You don’t call tools directly — you just talk to it, and it decides which tools to use. This page tells you what’s possible so you know what to ask for. Tools are split into two groups:

Core tools — always available, built into the agent
Plugin tools — enabled by config, extend the agent with new capabilities

Core tools

Notes

Create a note

Tool: create_note Save anything as a note — thoughts, research, meeting notes, journal entries, ideas. Notes are stored as Markdown files with YAML frontmatter, indexed for full-text and semantic search.

Save a note: I want to learn Rust this year, starting with the book.
Write a journal entry about today's standup.
Note this down: the API rate limit is 100 req/min per user.

Supports types: note (default) and journal. You can also provide tags and a category.

Read a note

Tool: get_note Retrieve the full content of a specific note by its ID.

Show me note abc-123.
What does note xyz-456 say?

List notes

Tool: list_notes Browse your notes — optionally filtered by type, read status, or date range.

List my recent notes.
Show me all my journal entries from last week.
What articles have I saved but not read yet?
List notes from January.

Update a note

Tool: update_note Change the title, content, tags, or category of an existing note.

Update note abc-123 — add the tag "important".
Change the title of note xyz to "Q1 Planning".
Append this to note abc-123: [text]

Delete a note

Tool: delete_note Move a note to the trash. By default, notes are soft-deleted — moved to trash and recoverable for 30 days. Use permanent=true to skip trash and remove immediately.

Delete note abc-123.
Remove that note I just saved.
Permanently delete note abc-123.

Trashed notes are automatically purged after 30 days by a background job. Use restore_note or list_trash to manage them.

View version history

Tool: note_history List past versions of a note with timestamps and a summary of what changed. History is created automatically each time a note is updated.

Show the history of note abc-123.
What versions exist for that note?
When was note abc-123 last changed?

Returns up to 10 revisions by default (max 50). Each entry shows the revision ID, timestamp, title at that point, and a diff summary (content, tags, category, or title changes).

Restore a previous version

Tool: restore_version Revert a note to a past version. The current state is saved as a new revision first, so nothing is lost.

Restore note abc-123 to revision rev-456.
Go back to the previous version of that note.

After restore, all indexes (SQLite, LanceDB) are updated with the recovered content.

List trash

Tool: list_trash Show all notes currently in the trash, with deletion date and days until permanent purge.

What's in the trash?
Show me deleted notes.
Did I delete anything recently?

Restore a note from trash

Tool: restore_note Recover a soft-deleted note from the trash back to its original location.

Restore note abc-123 from trash.
Undelete that note I just removed.

Search your knowledge

Tool: search_knowledge Find notes by meaning, not just exact words. Uses hybrid search (keyword + semantic vector search) by default, so it finds conceptually related content even when the exact phrasing differs.

Find everything I know about distributed systems.
Search for notes about anxiety.
What did I save about Rust's ownership model?
Find articles related to sleep and productivity.

Search modes: hybrid (default), keyword, or semantic.

Link notes

Tool: link_notes Create a bidirectional connection between two notes. Useful for building a knowledge graph.

Link note abc-123 to note xyz-456.
Connect the "Redis caching" note to the "API design" note.

Explore the knowledge graph

Tool: explore_graph Visualize and analyze the web of connections between your notes. Three modes:

around — describe all notes connected to a specific note or topic within N hops (default 2). Useful for discovering what you know about a subject and how ideas are related.
export — export the full graph in a machine-readable format: Mermaid diagram, DOT (Graphviz), or JSON (D3/vis.js node-link format).
stats — topology overview: total nodes/edges, connected cluster count, most-linked hub notes, and orphan notes (no connections yet).

Show me what's connected to note abc-123.
What's in my knowledge graph around "machine learning" (depth 3)?
Export my knowledge graph as Mermaid.
Export the graph as JSON.
How connected is my knowledge base? Show me the graph topology.
Which notes have the most connections?
Which notes aren't linked to anything?

Find similar notes

Tool: find_similar Given a note ID, finds the most semantically similar notes by comparing embedding vectors. Unlike search_knowledge (which takes a text query), this tool takes an existing note as the reference point and returns nearest neighbors ranked by similarity percentage.

Returns similarity as a percentage (0–100%)
Highlights shared tags and categories between the reference note and each result
Supports type filtering via excludeType to omit certain content types (e.g. reminders)
Excludes the reference note itself from results

Find notes similar to abc-123.
What's related to this note? (note id: xyz-456)
Show me notes like abc-123 but exclude reminders.

Categorize a note

Tool: categorize_note Ask the agent to automatically categorize an existing note using AI — assigns a category and tags, and in full mode also generates a summary, key points, and a one-line gist. After categorization, the tool automatically runs suggest_links and includes the top 3 link suggestions in the response.

Categorize note abc-123.
Auto-tag this note and generate a summary.
Run full processing on note xyz-456.

Modes: lightweight (category + tags only) and full (category + tags + summary + gist + key points).

Suggest links between notes

Tool: suggest_links Find semantically similar notes that could be linked to a given note. Uses vector similarity to surface related content you may want to connect. Suggestions include a similarity score and a brief reason (shared tags, shared category, or semantic similarity). Use link_notes to accept any.

Suggest links for note abc-123.
What notes are related to note xyz-456?
Find me notes I should link to this one.

Parameters: noteId (required), limit (default 5, max 20). Excludes notes already linked and notes from the same source URL (split content).

Synthesize notes

Tool: synthesize_notes Combine multiple notes into a new synthesis note. Select source notes by IDs, a search query, or tags. Supports four output formats.

Synthesize my notes about TypeScript patterns into a summary.
Create a comparison of my notes tagged "database".
Give me an executive brief from notes abc-123, def-456, ghi-789.
Create a timeline from my notes about the project launch.

Parameters: title (required), noteIds / query / tags (at least one), format (summary | brief | comparison | timeline, default summary), maxNotes (default 10, max 20). The synthesis note is auto-tagged with synthesis plus all source tags, and bidirectionally linked to every source note.

Mark content status

Tool: mark_content Track whether you’ve read, consumed, or archived a note or saved article.

Mark note abc-123 as read.
Archive that article — I'm done with it.
I've read the Redis docs, mark them as read.

Statuses: saved (unread, default), read (consumed), archived (hidden from search).

Note Templates

Use templates

Tool: use_template Manage and use note templates to quickly create structured notes. Templates are stored as markdown files with frontmatter in <knowledgeDir>/templates/. Five built-in templates are scaffolded automatically on first use: Meeting Notes, Book Review, Project Brief, Weekly Review, and Decision Log.

Show me available templates.
Create a meeting note using the meeting-notes template.
Create a new template for code reviews.

Actions:

list — Show all available templates with descriptions
use — Create a real note from a template, filling in {{placeholder}} variables
create — Save a new custom template with placeholder variables

Parameters: action (required), templateName (for use), variables (for use — fills placeholders), title, description, content, category, tags (for create).

Todos & Reminders

EchOS distinguishes two kinds of time-management items stored in the same underlying table:

Kind	Description	Due date
todo	Action item to do — no specific time required	Optional
reminder	Time-anchored item — will trigger a notification when due	Required

EchOS auto-detects todos: if your message contains first-person intent (“I need to…”, “I should…”, “remember to…”) it will silently capture a todo before responding.

Add a reminder or todo

Tool: add_reminder Use kind="todo" for action items; use kind="reminder" (or omit) for time-based reminders. If the scheduler is enabled, reminders will send a notification when due.

Remind me to review the PR tomorrow at 10am.
Add a high-priority reminder: renew SSL cert by March 1st.
I need to call the dentist.

List todos

Tool: list_todos Show your todo list. Returns only todos — never mixes in reminders or notes.

Show my todo list.
What tasks do I have pending?
What have I already done?

List reminders

Tool: list_reminders See your time-based pending (or completed) reminders.

What are my open reminders?
What do I have due this week?

Complete a reminder or todo

Tool: complete_reminder Mark any reminder or todo as done by id.

Mark reminder abc-123 as done.
I've completed that dentist task.

Memory

Remember something about you

Tool: remember_about_me Store a fact, preference, or detail about yourself in long-term memory. EchOS will use this in future conversations without you having to repeat it.

Remember that I prefer TypeScript over JavaScript.
I'm allergic to peanuts — save that.
Note that I'm working on a startup in the fintech space.
I prefer concise responses without bullet points.

Kinds: fact, person, project, expertise, preference.

Recall what EchOS knows about you

Tool: recall_knowledge Ask EchOS to surface everything it remembers about a topic or about you.

What do you know about my tech preferences?
Recall everything about my work projects.
What have I told you about my health?

Conversation

Save conversation

Tool: save_conversation Save a summary of the current conversation as a note — useful after a productive discussion you want to preserve. EchOS composes the summary itself from the visible conversation context.

Save this conversation.
Save a summary of what we discussed about the API design.
Note down what we figured out today.

EchOS will also proactively offer to save after personally significant exchanges — for example, after you recount a meaningful experience, share an emotional reflection, or make a significant life decision. It will ask first and only save once you confirm. It will not offer for short exchanges, factual queries, URL saves, or content already saved in the same session. Saved conversations are stored as type: conversation, status read, and are fully searchable via search_knowledge.

Export

Export notes or content

Tool: export_notes Export stored notes — or any piece of content, including agent responses and analysis results — as a downloadable file. Delivered directly in Telegram (as a document attachment), the CLI (stdout or --output), or the Web interface (as a download link).

Export note abc-123 as markdown.
Export all my notes tagged "recipes" as a zip.
Export everything I have about Redis as JSON.
Export that analysis you just did as a text file.
Export this conversation as a markdown file.

Formats:

Format	Extension	Best for
`markdown`	`.md`	Single notes with frontmatter intact
`text`	`.txt`	Plain readable text, markdown syntax stripped
`json`	`.json`	Structured data with metadata
`zip`	`.zip`	Multiple notes bundled together

You can also export arbitrary content — agent responses, analysis results, or anything from the current conversation — by just asking for it.

Reading Queue

Track your reading backlog and understand your reading habits. Works across all saveable content types — articles, YouTube videos, and tweets.

What’s in my reading queue?

Tool: reading_queue Lists your unread saved items (status: saved), sorted by relevance to your recent reading interests. Items whose tags and category match what you’ve been reading recently float to the top; recency acts as a tiebreaker. Filter by content type and set a limit.

What should I read next?
Show my reading list.
What's in my queue?
Show me unread articles.
Show me 5 unread YouTube videos.

Optional filters:

type — article, youtube, or tweet
limit — number of items to return (default: 10)

Each result shows the title, type, tags, save date, source URL, and a one-line gist (if the content was auto-categorized).

Reading stats

Tool: reading_stats Shows an overview of your reading progress across all saveable content.

How many articles have I read?
What's my read rate?
Show me my reading stats.
How productive have I been this week with reading?

Returns:

Overall: total saved / read / archived counts and read-rate percentage
Last 7 days: new saves and items read in the past week
By type: breakdown for articles, YouTube videos, and tweets

Tip: After discussing or finishing a saved item, tell EchOS — it will call mark_content to update its status to read automatically.

Knowledge stats

Tool: knowledge_stats Shows a comprehensive overview of your entire knowledge base — not just reading queue items, but every note type.

How many notes do I have?
Show me my knowledge base stats.
What are my most-used tags?
How has my collection been growing lately?
How much storage is my knowledge base using?

Returns:

Total notes with distinct tag and link counts
By type: breakdown for note, article, youtube, tweet, journal, image, conversation
By status: saved / read / archived / no-status counts
Weekly growth: last 8 weeks with sparkline (oldest → newest) and note-per-week counts
Activity streaks: current and longest consecutive-week streaks
Top 20 tags and top 10 categories by frequency
Storage: knowledge files, SQLite database, and vector database sizes

Tip: Use reading_stats for reading-queue progress; use knowledge_stats for a full picture of your collection.

Voice & personality

Set agent voice

Tool: set_agent_voice Change how EchOS talks to you — tone, warmth, verbosity, formality, personality. Takes effect immediately and persists across sessions.

Be more concise.
Be warmer and more encouraging.
Use a formal, professional tone.
Be playful, use light humour.
Reset your voice to default.

See Writing & Voice for the full guide.

Plugin tools

Plugins extend EchOS with additional capabilities. Enable them via config.

Article plugin

Save a web article

Tool: save_article Fetch any URL, extract the article content (using Mozilla Readability), and save it as a note. Strips ads, navigation, and boilerplate — keeps the actual content.

Save this article: https://example.com/post
Save and auto-categorize: https://example.com/post

Optional: autoCategorize (runs AI categorization on save), processingMode (lightweight or full).

Twitter plugin

Save a tweet or thread

Tool: save_tweet Fetch any Twitter/X URL and save the tweet or thread as a note. Uses the free FxTwitter API — no Twitter API key needed. Threads are automatically unrolled into clean article format.

Save this tweet: https://x.com/user/status/123456789
Save this thread: https://twitter.com/user/status/123456789

Supported URL formats: twitter.com, x.com, mobile.twitter.com, fxtwitter.com, vxtwitter.com. Saved content includes: tweet text, author, date, engagement stats (likes, retweets, replies, views), media URLs, and quote tweets. Threads (chains of same-author replies) are merged into clean article format. Optional: autoCategorize (default: true — runs AI categorization automatically), processingMode (lightweight or full), tags, category (default: tweets).

YouTube plugin

Save a YouTube video

Tool: save_youtube Extract the transcript from a YouTube video and save it as a note. Great for preserving content from talks, tutorials, and interviews.

Save this video: https://youtube.com/watch?v=...
Save and summarize this talk: https://youtu.be/...

Optional: autoCategorize, processingMode.

Image plugin

Save an image

Tool: save_image Save an image to your knowledge base — via URL or by sending the image directly. Extracts metadata (dimensions, format, EXIF data) and optionally runs AI analysis.

Save this image: https://example.com/photo.jpg
[send image in Telegram] Save this with the tag "inspiration"
Analyze and save this screenshot.

On Telegram, you can just send an image and ask EchOS to save it.

Content-creation plugin

Write content in your voice

Tool: create_content Generate long-form content that sounds like you — blog posts, articles, threads, emails, essays, and tutorials. Uses your style profile (built from voice examples you curate) and pulls relevant notes from your knowledge base as context.

Write a blog post about burnout in tech.
Draft a Twitter thread about Rust's memory model.
Write an email to my team about the Q2 roadmap.
Write a tutorial on setting up LanceDB.

Content types: blog_post, article, thread, email, essay, tutorial You can also specify: length, audience, and extra instructions. See Writing & Voice for the full guide.

Analyze your writing style

Tool: analyze_my_style Build a detailed profile of your writing voice from pieces you’ve curated as examples. Run this after you’ve tagged at least 5 notes as voice examples.

Analyze my writing style.
Re-analyze my style — I've added new examples.

View your style profile

Tool: get_style_profile Display your current writing style profile — tone descriptors, vocabulary characteristics, sentence patterns, formality level, and sample paragraphs.

Show me my style profile.
What have you learned about how I write?

Mark a voice example

Tool: mark_as_voice_example Tag a note as a voice example so it gets included in style analysis. Best with polished, representative writing of 500+ words.

Mark note abc-123 as a voice example.
Tag my "distributed systems post" as a voice example.

Resurface plugin

Resurface forgotten notes

Tool: get_resurfaced Bring back notes you’ve forgotten about using spaced repetition and on-this-day discovery. Returns 2–3 notes (configurable) with labels showing why each was selected. Updates each note’s last-surfaced timestamp so it won’t repeat within 7 days.

Surprise me.
What did I save about a year ago?
Show me something from my knowledge base I've forgotten.
On this day — what was I thinking about?
Give me a random note.

Modes:

mix (default) — blend of forgotten notes and on-this-day
forgotten — oldest un-surfaced notes first (spaced repetition)
on_this_day — notes created on this calendar date in a prior year
random — purely random sampling of un-recently-surfaced notes

See the Resurface Plugin for setting up a daily broadcast schedule.

Digest plugin

The digest plugin runs as a scheduled background job (not a direct tool). It generates a summary of recent notes — including a Reading Queue section with your top 3 unread items — and broadcasts it to your configured notification channel (Telegram). Configure it via the scheduler:

Schedule a daily digest at 8am.
Send me a weekly digest every Sunday.

Quick reference

What you say	Tool
”Save a note about…”	`create_note`
”Search for…”	`search_knowledge`
”List my recent notes”	`list_notes`
”Update note abc-123”	`update_note`
”Delete note abc-123”	`delete_note` (moves to trash)
“Permanently delete note abc-123”	`delete_note` (permanent=true)
“What’s in the trash?”	`list_trash`
”Restore note abc-123 from trash”	`restore_note`
”Show history of note abc-123”	`note_history`
”Restore note to previous version”	`restore_version`
”Remind me to…”	`add_reminder` (kind=reminder)
“I need to / I should…”	`add_reminder` (kind=todo, auto-detected)
“What are my todos / tasks?”	`list_todos`
”What are my reminders?”	`list_reminders`
”Mark reminder/todo done”	`complete_reminder`
”Remember that I prefer…”	`remember_about_me`
”What do you know about me?”	`recall_knowledge`
”Save this conversation”	`save_conversation`
”Export this as a zip”	`export_notes`
”Categorize note abc”	`categorize_note`
”Link these two notes”	`link_notes`
”Suggest links for note abc”	`suggest_links`
”What notes are related to this one?”	`suggest_links`
”What’s connected to note abc / around this topic?”	`explore_graph` (action=around)
“Export my knowledge graph”	`explore_graph` (action=export)
“Show graph topology / hub notes / orphans”	`explore_graph` (action=stats)
“Find notes similar to abc-123”	`find_similar`
”Show me available templates”	`use_template` (action=list)
“Create a meeting note from template”	`use_template` (action=use)
“Create a new template for X”	`use_template` (action=create)
“Synthesize my notes about X”	`synthesize_notes`
”Create a brief from these notes”	`synthesize_notes`
”Compare my notes tagged Y”	`synthesize_notes`
”Mark article as read”	`mark_content`
”What should I read next?”	`reading_queue`
”Show my reading list / queue”	`reading_queue`
”Show unread articles / videos”	`reading_queue`
”What’s my read rate / reading stats?”	`reading_stats`
”How many notes do I have / knowledge stats?”	`knowledge_stats`
”What are my top tags / most used categories?”	`knowledge_stats`
”How much storage is my knowledge base using?”	`knowledge_stats`
”Be more concise”	`set_agent_voice`
”Surprise me / on this day / random note”	`get_resurfaced`
”Save this article: URL”	`save_article`
”Save this tweet: URL”	`save_tweet`
”Save this YouTube video: URL”	`save_youtube`
”Save this image”	`save_image`
”Write a blog post about X”	`create_content`
”Analyze my writing style”	`analyze_my_style`
”Show my style profile”	`get_style_profile`
”Mark this as a voice example”	`mark_as_voice_example`

Getting Started

Architecture

Features

Operations

​Tools Reference

​Core tools

​Notes

​Create a note

​Read a note

​List notes

​Update a note

​Delete a note

​View version history

​Restore a previous version

​List trash

​Restore a note from trash

​Search your knowledge

​Link notes

​Explore the knowledge graph

​Find similar notes

​Categorize a note

​Suggest links between notes

​Synthesize notes

​Mark content status

​Note Templates

​Use templates

​Todos & Reminders

​Add a reminder or todo

​List todos

​List reminders

​Complete a reminder or todo

​Memory

​Remember something about you

​Recall what EchOS knows about you

​Conversation

​Save conversation

​Export

​Export notes or content

​Reading Queue

​What’s in my reading queue?

​Reading stats

​Knowledge stats

​Voice & personality

​Set agent voice

​Plugin tools

​Article plugin

​Save a web article

​Twitter plugin

​Save a tweet or thread

​YouTube plugin

​Save a YouTube video

​Image plugin

​Save an image

​Content-creation plugin

​Write content in your voice

​Analyze your writing style

​View your style profile

​Mark a voice example

​Resurface plugin

​Resurface forgotten notes

​Digest plugin

​Quick reference