Local knowledge for your AI agents.
Your notes, documents, mail and messages in one local store — linked to people, tagged, and searchable
with a reference to every source.
memo is a command-line tool. It imports a folder of notes such as an Obsidian vault, the documents in
it, and your mail; it reads the messages that tg-cli and
max-cli keep. Then you, or your AI agent, ask: what do I know
about this person, where did we discuss this, what did I promise. Every answer points back to its source.
Example — two invented notes in a vault, people/Alice Example.md and Projects/Harbour budget.md:
$ memo search notes budget Friday
Projects/Harbour budget.md
# Harbour budget
people/Alice Example.md
Asked for the revised budget by Friday. See [[Harbour budget]].
Linked from these notes
Alice Example document:2 (1)
Bob Sample (nobody by that name yet) (1)
Harbour budget document:1 (1)
Each hit names its file, and [[links]] become links to notes and people. Bob Sample becomes a link to
a person once someone by that name is in the store.
You need Node.js 22.16 or newer.
npm install -g @wirecat/cli-memo
memo folders add /path/to/notes # your notes folder; Obsidian format by default
memo sync --only notes # reads the notes, their links and tags; run again after edits
memo search notes "budget"That is all notes need. Then add more context:
- Messages: install tg-cli or max-cli; memo reads the same local store.
- Search by meaning:
tg models text download e5-smalldownloads the local model once. - Mail: set up Himalaya, then
memo sync --only mail. - Stay current:
memo auto startrunsmemo syncevery five minutes (Linux, systemd). - Your agent: the install puts memo's skill where Claude Code, Codex and Gemini CLI read it;
memo skill showprints it,memo skill install --for allinstalls it again.
Or ask your agent: "Help me install memo with npm install -g @wirecat/cli-memo, read memo --help, then
help me connect a notes folder I choose."
More: installation · install memo on wirecat.dev
"What do I need to know about Alice before the call?"
memo context telegram:"Alice Example" --jsonEvery identity linked to her, the last message each way, chats in common, linked mail, the notes about her and the open tasks — each with a link to its source.
"Where did we discuss the Harbour budget?"
memo search all 'harbour budget' --jsonMessages, imported mail and notes, ranked together. When you know the kind, search notes,
search mail and search messages read every field.
"What did I promise people this week?"
memo ask 'What did I promise this week?' 'promised OR "by Friday"' --all --jsonAn evidence bundle for your agent: the matching sources with their references, what was searched, and the instruction to cite them. Your agent writes the answer; memo calls a model only when you ask it to.
More: search · ask for the context you need
- Any agent with a terminal — Claude Code, Codex, Gemini CLI and others run
memocommands;--jsongives them structured output. - Evidence, not guesses —
memo askhands over sources with references, and says what it could not search. - MCP —
memo mcplets MCP apps such as Claude Desktop or Cursor propose memories, facts and actions and read the agent log; they wait for you to confirm.
More: connect your AI agent · memories and facts · the MCP server
- Local first. Everything lives in a local store; search by meaning uses a local model.
- Every answer has a source. Hits carry a reference you or your agent can open: a note, a file page, an email, a message.
- Links, not guesses. Notes link to people and records; identities are never merged because a name matches.
- Your sources stay untouched. Folders and mailboxes are read-only; tags and your own notes live in the store.
- Agents propose, you decide. Memories and actions an agent suggests wait for your confirmation; nothing is ever sent.
Status: early. Context, notes and their links, document import, Gmail and IMAP imports, tasks, manual relationships, evidence bundles and local reminders work.
More: security · security on wirecat.dev
- Folders of notes: Obsidian or plain Markdown, with links, aliases and tags.
- Documents in them: TXT, CSV/TSV, text-layer PDF, DOCX, XLSX, ODT/ODS, PPTX and EPUB, with the page, row or cell each passage came from.
- Mail: Gmail or another IMAP account, through Himalaya, attachments included.
- Messages: the tg and max store, with the people linked across messengers and mail.
You add your own notes about messages, people and projects, tags, tasks and reminders, organizations and projects.
More: notes · files memo can read
| Task | Commands |
|---|---|
| Connect notes folders | memo folders add · folders attach · folders list |
| Sync what changed | memo sync · sync --only notes · sync --only mail · auto start / stop / status |
| Read notes | memo notes list · notes show · memo note (the note about a person) |
| Write your own notes | memo notes add · notes edit · notes remove · notes export |
| Search | memo search all · search notes · search mail · search messages |
| Hand evidence to an agent | memo ask |
| Know a person | memo context |
| Organizations and projects | memo organizations add / list / context · projects add / list / context · projects key-documents add / remove / list · projects meetings list / link |
| Project and topic aliases | memo vocabulary list / resolve / preflight · vocabulary aliases add / remove · vocabulary create |
| Relationships | memo relationships add / list / remove / confirm / suggest |
| Labels | memo tags add · tags remove · tags list |
| Open work | memo tasks add · tasks list · tasks agenda · tasks plan · tasks show · tasks update · tasks assign · tasks close · stats tasks show |
| Task dependencies | memo tasks link / unlink / relations · tasks status · tasks list project:HRB ready:true |
| Reminders | memo reminders add / list / poll / ack / update / cancel |
| Agents | memo memories … · facts … · actions … · agents log · memo mcp |
Every command takes --help; most take --json.
More: technical docs · memo on wirecat.dev
From a folder. memo folders add gives a folder an id that the store uses; its path is only where it is
on this computer, so the same folder on another computer is attached with memo folders attach <id> <path>.
memo sync --only notes stores each file as a note named by its path. An edited file keeps its old text as a
revision; a moved file keeps its id, links and tags; a deleted file loses its text on the next import. The
obsidian format (the default) reads [[Note|label]] links, aliases, tags: and #tags; markdown reads
[label](path.md) links and tags:. A [[Kai Sample]] link becomes a link to a person once someone by that
name is in the store. Hidden folders such as .obsidian are skipped.
Written in memo. A note you write is the store's, not a file's, and is about whatever --subject names: a
person, a message, a chat, a project, a task, another note.
memo notes add 'Prefers mornings' --subject telegram:'Alice Example'
memo notes edit NOTE_ID --revision 1 --text 'Prefers early mornings'
memo notes export --output-dir /path/to/vault/memo --format obsidianAn edit names the revision it changes, so an edit made meanwhile is never lost. export writes your notes
as files that import then skips, and never overwrites a file you edited.
More: notes · add your notes · create your own notes
Notes are searched by words and word stems in the query language messages use — phrases, AND/OR/NOT,
tag:, date: — and by meaning once the local model is downloaded; both are ranked together. search all
reads messages, imported mail and notes together, and nothing else. When you know the kind, its own search
reads every field: search mail takes from:, to:, cc:, bcc:, subject: and mailbox:.
memo search notes '"budget review" AND NOT cancelled' --limit 20
memo search mail 'from:alice@example.com subject:budget'
memo notes show note:NOTE_ID --jsonmemo ask needs a scope (--all, or --provider with --account) and returns evidence by default. To
call a model instead, set MEMO_MODELS_ANALYSIS_PROVIDER and MEMO_MODELS_ANALYSIS_MODEL and pass
--analyze; a remote model also needs --allow-remote.
More: search · searching on wirecat.dev
memo context answers from the shared store: every identity linked to the person, the last message each
way, recent messages, chats in common, linked mail, the notes about them and the open tasks. Who is who is
decided in messaging — tg contacts link <person> email:<address> — and a same name is never enough.
memo note telegram:"Alice Example" /path/to/notes/people/Alice.md names the note that is about her.
Organizations and projects are yours, not one account's. Relationships (member-of, related-to) are
manual statements; relationships suggest only proposes shared-domain links for you to confirm. A project
can hold meetings (projects meetings link), and memo vocabulary gives projects and topics reviewed
aliases, so one name always means one project.
Before adding a new tag or topic, run memo vocabulary check <name> --json. Reuse a
canonical label or add an alias if it means the same thing. For a deliberately distinct label,
run memo vocabulary create <name> --fingerprint <creation_fingerprint> --json; select --kind topic
on both commands when creating a topic. The owner accepts this review; MCP exposes preflight
but no label-creation tool. An intervening label or alias change requires a fresh review.
memo vocabulary check --json finds likely synonyms already in the catalog. Its complete
flag reports whether the bounded comparison finished; candidates require review and are never
merged automatically. Use --kind tag, --kind topic or --kind project to narrow the review.
memo organizations add 'Synthetic Studio' --kind company
memo projects add 'Synthetic Harbour' --organization organization:ORGANIZATION_ID
memo projects key-documents add PROJECT_ID document:DOCUMENT_ID --reason 'read this first'
memo projects context PROJECT_ID --json # start project work here: key documents come firstMore: people and projects · people on wirecat.dev
memo reads mail through Himalaya, a command-line mail client you
set up first. Gmail is the default; another IMAP provider uses mode: "imap" with the folders to read. The
mailbox is opened read-only, --limit (default 200) bounds the new mail per run and the next run continues.
Gmail labels become mailboxes, attachments' text is searched with its email, and mail deleted at the
source loses its text in the store. Each account is named in mail.accounts; memo sync and the timer read
every account and name each in the report, and --account <name> narrows it to one.
memo sync --account work --since-time 2026-09-01 # work: the account's name in mail.accounts
memo search mail 'mailbox:important budget'More: mail · email on wirecat.dev
Tags are your labels on a note, an email, a message, a chat, a person, an organization, a project, a task,
a meeting, or every note under a folder. They live in the store; files, Gmail labels and mailbox flags are
never changed. A task points at the message or note it came from, or is your own in a
project (--project RES --title …), and can be blocked by another until it is done. memo tasks agenda
says what needs a look today, across every messenger account the store holds. Reminders are local:
a caller you choose polls for them, and nothing is delivered to a messenger or mailbox.
memo tags add follow-up --note note:NOTE_ID
memo tasks add 'msg:telegram/1/77/42' --type request
memo reminders add TASK_ID --at-time 2026-10-09T09:00:00+02:00 --provider telegram --account 1More: tags · tasks and reminders · tag your sources
An agent with a terminal runs memo with --json. An MCP app starts memo mcp, which serves memories,
facts, proposed actions and the agent log on stdin and stdout:
{ "mcpServers": { "memo": { "command": "memo", "args": ["mcp"] } } }An agent's memories, facts and proposals wait as proposed; it cannot confirm, accept, approve or reject. Approving an
action makes it your task; nothing is ever sent. memo agents log lists every call — the agent, the tool,
the outcome and the times, never the arguments. Search and context are not served over MCP.
More: memories and facts · the MCP server · MCP on wirecat.dev
memo sync brings notes and mail up to date and reads only what changed. memo auto start --every 5m runs
it on a systemd user timer; auto status shows the next and last run, and while timer runs fail every memo
command says so in one stderr line. A lock keeps two imports apart: a
timer run that finds a sync still running skips and exits 0. One failing source does not stop the others.
More: keeping memo up to date · import a folder on wirecat.dev
memo folders add and memo auto start write ~/.config/cli-memo/config.json for you. By hand you set what
to skip, mail accounts and where exported notes go:
{
"notes": { "ignore": ["Journal/Private.md", "Archive"], "export": { "dir": "/path/to/vault/memo" } },
"mail": { "accounts": [{ "name": "work", "address": "you@example.com" }] }
}More: configuration · configuration on wirecat.dev
- Note folders and mailboxes are read-only; nothing is sent, moved or marked read.
- What memo adds — your notes, links, tags, tasks, memories — stays in the local store.
- A note or mail deleted at the source loses its text in the store on the next import; a run that finds an unusually large share missing deletes nothing and says so.
- Evidence reaches a model only with
--analyze, and a remote one only with--allow-remote. - Agents propose; only you confirm memories and approve actions.
More: security · security on wirecat.dev
- Files up to 50 MiB; stored text up to 200,000 characters a file. Scanned PDFs and legacy DOC/XLS are reported, not read.
- Search by meaning embeds at most 600 chunks a run; the next run continues.
memo sync --only mailreads 200 new messages per account a run by default (--limit) and keeps up to 1,000,000 characters of a body and 200,000 of an attachment's text (mail.max_body_chars,mail.max_attachment_chars).- Searches return at most 100 results;
tags listshows 100 labels unless--limitsays more. - Tags are 1–32 letters a–z, digits or hyphens.
More: files memo can read · files memo can read
- Searched by words only: the meaning model is not downloaded —
tg models text download e5-small. - A folder is refused by import: it has no id yet —
memo folders add <path>. - A name is refused: two people share it; use one of the ids it lists.
memo askasks for a scope: add--all, or--providerwith--account.- An empty search: the store holds nothing that matches — not proof that it never happened. Try the kind's own search, looser words, or import that source first.
More: if something is missing · search
WireCat is an open-source, local-first context layer for AI agents: tg for Telegram, max for MAX, memo for your notes and mail, all in one local store. Start with your notes. Add more context when you need it. Your context. Any agent.
| Page | What it covers |
|---|---|
| Overview | What memo does and how it works, in short |
| Installation | Requirements, install, where files go, update |
| Using memo | A normal day: import, search, context, notes, review |
| How memo works | The local store, imports, links, references, review |
| Notes and folders | Markdown and Obsidian folders, documents, your own notes, export |
| Tags | Labels on any source |
| Search | Search words, search all, ask |
| People and projects | Person context, linking, organizations, relationships |
| Gmail and IMAP through Himalaya | |
| Tasks and reminders | Tasks, dependencies and local reminders |
| Memories and facts | What agents and you record, and proposed actions |
| The MCP server | Apps without a terminal, the agent log |
| Keeping memo up to date | memo sync and the timer |
| Recipes | Whole tasks to hand to your agent |
| All commands | Every command and option, generated |
| Configuration | Every setting and variable |
| Troubleshooting | What the screen says, and what to do |
| Security | What is read, written and sent |
| Changelog | Every release |
The reader guides live on wirecat.dev.
pnpm install
pnpm lint && pnpm typecheck && pnpm testPull requests are welcome; examples and tests use invented people only.
More: installation