Repository navigation
installation
Read this page before you run Memo for the first time, when you move to another computer, and when you update or remove Memo. When you are done, Memo is installed, you checked that it runs, and you know where it keeps its files. Adding your notes and mail is the next step, on its own pages.
Words this page uses:
-
npm package: how Memo is shipped. npm (or pnpm, or Bun) downloads it and puts the
memocommand on your computer. The package is@wirecat/cli-memo; the command it installs ismemo. - Node.js: the program that runs Memo. Install it first.
-
PATH: the list of folders where the terminal looks for a command by its name.
memoruns by name only if its folder is on the PATH. - The local store: one database file on your computer that holds the text of your notes, mail and messages. Memo shares it with tg and max.
- Skill: short instructions that tell an AI agent how to use Memo.
Installing does not log in anywhere, does not start a background service and does not read your notes or mail. Memo
reads a folder or a mailbox only when you add it and run memo sync. Syncing on a timer is a separate step that you
turn on with memo jobs start.
- Node.js 22.16+ (the 22.x line) or 24+, with npm. Node.js 23 is not supported. If you do not have it, ask your agent to help, or get it from nodejs.org. The command also runs under Bun; CI runs the built command under Bun too.
- Linux. macOS and Windows are not tested yet: memo's tests run on Linux only.
- About 250 MB of disk for the install. Most of it is shared WireCat code that memo does not use yet: charts, speech recognition and audio decoders.
Each source needs one more thing, and only when you use it:
| Source | What it needs |
|---|---|
| Notes and documents | Nothing: files Memo can read |
| Telegram or MAX messages | tg or max. They save your chats in the local store; Memo does not log in to a messenger |
| Search by meaning | A search model on your computer, about 220 MB. Download it once: memo models download embeddinggemma. Without it, Memo searches by words |
| The mail CLI. It copies your mailbox into the local store, and Memo searches it (mail). | |
Syncing on a timer (memo jobs) |
Linux with systemd. On macOS and Windows, run memo sync yourself or from your own scheduler (keeping Memo up to date) |
The easiest way: ask your agent.
Install Memo with npm install -g @wirecat/cli-memo, then run memo skill install --for all.
Check Node.js and npm first and help me set them up if needed.
Then run memo --version and memo --help and tell me if it works.
Or install it yourself:
npm install -g @wirecat/cli-memo
memo skill install --for all # puts Memo's skill where your agents read itnpm 11.17 and later warn about install scripts not covered by allowScripts; with npm 11 the scripts still run.
npm 12 blocks them instead. Run the npm install -g --allow-scripts=… command npm prints under the warning;
it allows only the packages it names, once. Then run memo skill install --for all to install the agent skill.
On Windows, open a new terminal if memo is not found. With pnpm or Bun, pnpm add -g @wirecat/cli-memo or
bun add -g @wirecat/cli-memo, then the same memo skill install --for all.
To try it without installing (Node.js still runs it):
npx @wirecat/cli-memo --help
pnpm dlx @wirecat/cli-memo --help
bunx @wirecat/cli-memo --helpCheck that it works:
memo --version
memo --help # the list of commands
memo doctor # the state this installation is in; --online also asks npm for a newer memo
memo commands --json # every command and option, for agents and scriptsmemo doctor lists the settings file, the store, your notes folders, the search
model, the timer and the agent skill. Each problem comes with the command that fixes it, and the command exits 1
while something needs attention. Problems in the settings file are listed too, in config.issues of
memo doctor --json, the same shape every WireCat tool's doctor uses. The settings file, its folder, the store and
the run log folder are checked for other users being able to read them; any that can are listed in files.problems
with the mode they have and the one they should have, and the chmod that fixes each is printed. Neither settings
problems nor open files change the exit code from 0, so the report still reads as an answer. memo doctor --json
gives the same for an agent.
memo --help lists commands such as notes, search, mail and sync. If the install finished but the terminal
says memo is not found, open a new terminal: a terminal that was already open does not see a new command. If it is
still not found, the folder where your package manager puts commands is not on the PATH. npm prefix -g shows that
folder (on Linux and macOS the command is in its bin folder); add it to the PATH, or ask your agent to.
Memo has no login and no setup step. Add a folder of notes, read it, and search it:
memo folders add ~/Documents/Notes # your notes folder; Obsidian format when it is a vault
memo sync --only notes # reads the notes, their links and tags
memo search notes "budget"Then add more folders or connect a mail account.
Your agent's skill. memo skill install --for all puts Memo's skill where Claude Code
(~/.claude/skills/cli-memo/) and Codex or Gemini CLI (~/.agents/skills/cli-memo/) read it; --for claude or
--for agents installs it for one. memo skill show prints it. A global npm install does the same only when
MEMO_INSTALL_AGENT names where: all, claude, codex, cursor or gemini; unset or none, it installs no skill.
Windows is not tested yet; these steps are what should work. Open PowerShell and use npm.cmd, because PowerShell can block the npm script:
npm.cmd install -g @wirecat/cli-memo
memo --versionThen open a new terminal: npm cannot change the PATH of the terminal it runs in. The Node.js installer usually puts
npm's command folder on the PATH already; npm.cmd prefix -g shows which folder that is.
You need this to change Memo's code, or to use a version that is not released yet.
git clone git@github.com:WireCatLabs/cli-memo.git
cd cli-memo
pnpm install
pnpm buildThen either put the command on the PATH:
pnpm link --global # now plain `memo` worksor run it by its path, without linking:
node dist/bin/memo.js --help| What | Linux and macOS | Windows |
|---|---|---|
| Settings | ~/.config/cli-memo/ |
%APPDATA%\cli-memo\Config\ |
| State | ~/.local/share/cli-memo/ |
%LOCALAPPDATA%\cli-memo\Data\ |
Cache, which memo doctor names; Memo keeps nothing there yet |
~/.cache/cli-memo/ |
%LOCALAPPDATA%\cli-memo\Cache\ |
| The local store, shared with tg and max | ~/.local/share/WireCat/wirecat.db |
%LOCALAPPDATA%\WireCat\Data\wirecat.db |
| Shared search models | ~/.local/share/WireCat/models/ |
%LOCALAPPDATA%\WireCat\Data\models\ |
The timer, after memo jobs start
|
~/.config/systemd/user/memo-import.timer and .service
|
— |
-
Settings:
config.json(configuration): your folders and the timer. -
State: what this computer imported last from each folder (
folders/), the lock that stops two syncs at once (import.lock), and how the last timer run ended (auto/). - The local store holds your notes, mail, messages, tags, tasks and memories. Your note files and your mailbox stay where they are; the store holds a copy of their text.
~ means your home folder. Environment variables move each place: MEMO_CONFIG_DIR (settings), MEMO_STATE_DIR
(state), MEMO_CACHE_DIR (cache), MESSAGING_STORE (the store file itself) and WIRECAT_STATE_DIR (the WireCat
folder: the store and the models).
The task commands also read ~/.config/cli-memo-tasks/config.json (MEMO_TASKS_CONFIG_DIR moves it) when it exists.
Memo never writes it, and you do not need it. The timer runs memo sync with MEMO_AUTO=1, which marks a timer run:
it skips the update check and, when the timer is off in the settings, does nothing.
⚠ Set these variables everywhere, or nowhere. A command run without them reads other settings and another store, and says your folders or mail are not there. The timer keeps the ones set when you ran
memo jobs start; run it again after you change them. tg and max read the same store only when they get the sameMESSAGING_STOREorWIRECAT_STATE_DIR. The variables are meant for tests and throwaway profiles.
memo upgrade --check # only say whether a newer version exists; installs nothing
memo upgrade # update with the package manager that installed Memo: npm, pnpm or Bun
memo skill install --for all # the skill of the new versionOnce a day Memo asks npm whether a newer version exists and, if so, prints one line after a command, on stderr. Only
a person at a terminal sees it: not with --json, not in a pipe, not on the timer's runs. Turn it off with
"update_check": false in the settings, or MEMO_NO_UPDATE_CHECK=1. Memo never updates itself.
-
The timer runs the updated Memo on its next run; nothing to restart. After you change Node.js versions (for
example with nvm) and install Memo there, the next
memocommand you run points the timer at that Memo, so removing the old Node.js does not break it. Only a global install moves the timer: a Memo run from a checkout, withnpxor from another tool's ownnode_modulesleaves it alone. -
memo mcp servekeeps running the old version until your agent restarts it. Restart the agent, or its MCP server.
From sources: git pull && pnpm install && pnpm build.
Removing Memo takes away the command, not your data. Do it in this order:
memo jobs stop # if you turned on the timer: removes it while memo still exists
npm uninstall -g @wirecat/cli-memo # or pnpm remove -g, or bun remove -g
rm -rf ~/.claude/skills/cli-memo ~/.agents/skills/cli-memo # the agent skill
rm -rf ~/.config/cli-memo ~/.local/share/cli-memo ~/.cache/cli-memo # Memo's settings, state and cacheThe local store stays. tg and max use it too, and it holds your notes, mail, tags and memories. Delete
~/.local/share/WireCat/ only if no other tool uses it: it holds everything each of them saved.
To work on Memo itself, build it from sources, then run the checks:
pnpm lint && pnpm typecheck && pnpm test