> ## Documentation Index > Fetch the complete documentation index at: https://docs.echos.sh/llms.txt > Use this file to discover all available pages before exploring further. # Tools Reference > Everything EchOS can do — a plain-language guide to every tool available to the agent. # 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 `/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](/writing) 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](/writing) 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](/plugins#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` |