Command line¶
The localmem-mcp command does double duty: with no arguments it runs the MCP
server (that's what clients invoke), and its subcommands let you inspect and
edit the same database from a terminal.
Shared flags work either before or after the subcommand, so both of these are valid:
serve¶
Run the MCP server over stdio. This is the default when no subcommand is given.
It reads and writes JSON-RPC on stdin/stdout, so running it in a terminal looks like it's hanging — that's correct. It's waiting for a client.
add¶
Store a memory.
localmem-mcp add "Deploys go out on Thursdays" --tag ops --tag process
localmem-mcp add "Priya prefers async updates" --source standup
| Flag | Description |
|---|---|
--tag TAG |
Add a tag. Repeat for several. |
--source SOURCE |
Where the memory came from. |
search¶
Search memories by meaning.
localmem-mcp search "when do we ship?"
localmem-mcp search "deployment" --tag ops -n 10 --min-score 0.4
| Flag | Default | Description |
|---|---|---|
-n, --limit |
5 |
Maximum results. |
--tag TAG |
— | Only memories with all given tags. Repeatable. |
--min-score |
0.0 |
Drop results below this score. |
recall¶
Read a memory by id, or the most recent ones.
Exits with status 1 if the id doesn't exist, so it's safe to use in scripts.
forget¶
Delete a memory by id, or bulk-delete by tag and/or age.
localmem-mcp forget 7 # one specific memory
localmem-mcp forget --tag stale # every memory tagged "stale"
localmem-mcp forget --older-than 90d # everything older than 90 days
localmem-mcp forget --tag scratch --older-than 30d --yes
| Flag | Description |
|---|---|
memory_id |
Delete the single memory with this id. |
--tag TAG |
Bulk-delete memories with this tag. Repeatable — all tags must match. |
--older-than DURATION |
Bulk-delete memories older than this. Accepts 90, 90d, or 8w. |
--yes |
Skip the confirmation prompt for bulk deletes. |
Single-id delete:
Bulk delete shows what will be removed and asks before deleting — deleting someone's memories on a typo is unforgivable:
#12 (2026-05-01T09:00:00+00:00) [stale] Old deploy notes
#9 (2026-03-14T18:30:00+00:00) [stale] Abandoned experiment
Delete 2 memories? [y/N]
Answer y to delete, anything else aborts without touching the store. Pass
--yes to skip the prompt in scripts. A bulk call with no filter at all
exits with status 2 rather than wiping the database.
With --json, the result is a single machine-readable payload (the
human-readable preview and prompt go to stderr):
stats¶
Show the database location, memory count, and active model.
JSON output¶
Every subcommand takes --json, which prints the same structures the MCP tools
return:
[
{
"id": 7,
"content": "Deploys go out on Thursdays",
"tags": ["ops", "process"],
"source": null,
"metadata": {},
"created_at": "2026-08-14T11:31:00+00:00",
"updated_at": "2026-08-14T11:31:00+00:00",
"score": 0.8121
}
]
Which makes jq pipelines straightforward:
# Just the text of the top three matches
localmem-mcp search "deploys" -n 3 --json | jq -r '.[].content'
# Every memory tagged "decision", newest first
localmem-mcp recall -n 100 --json | jq -r '.[] | select(.tags[]? == "decision") | .content'
# Back everything up as JSONL
localmem-mcp recall -n 100000 --json | jq -c '.[]' > memories.jsonl
Useful recipes¶
Pre-warm the model so an agent never waits on the first-run download:
Bulk-import notes, one memory per line:
while IFS= read -r line; do
[ -n "$line" ] && localmem-mcp add "$line" --tag imported --source notes.txt
done < notes.txt
Check what your agent has been remembering:
Inspect the raw database — it's just SQLite:
sqlite3 ~/.localmem/memories.db \
"SELECT id, created_at, substr(content, 1, 60) FROM memories ORDER BY id DESC LIMIT 10;"
Prefer the CLI for writes
Reading the database directly is fine. Writing to it by hand isn't — an
INSERT that skips the embedding step produces a memory that search can
never find.