cli-memory

Local-first, private long-term memory for AI agents. Everything runs on your machine, including embeddings.

npm install -g cli-memory

Requires Node.js >= 20.

Quick start

# First use downloads the default local embedding model if needed.
cli-memory store "The user prefers warm water" --topic health --memory-type Preference --importance 8
cli-memory search "warm water" --topic health

# Web console + REST API at http://127.0.0.1:3456
cli-memory serve

# Optional: keep a background process alive for faster repeated CLI calls
cli-memory serve --daemon
cli-memory status

What it is

cli-memory gives agents a durable, searchable memory layer outside the chat window.

• Data stays on local disk in LanceDB.
• Memories are partitioned by explicit topicKey.
• Search combines vector similarity and full-text search.
• importance >= 7 is treated as long-term memory, while lower scores remain searchable as working memory.
• The same system can index local docs and URLs into searchable collections.

Why use it

• Private by default: no cloud dependency for storage or the default embedding path
• Agent-friendly: use it from CLI, cli-memory call, REST, or the built-in web console
• Fast local workflows: serve --daemon lets repeated CLI calls reuse a long-lived process
• Useful retrieval: results are reranked with importance, recency, and access history

Core workflows

1. Store and recall memories

cli-memory store "The user prefers warm water" --topic health --memory-type Preference --importance 8
cli-memory search "warm water" --topic health
cli-memory list --topic health --limit 10
cli-memory list --topic health --tiers long-term
cli-memory retrieve-context "health preferences" --topic health
cli-memory supersede mem_001 "The user now prefers cold water" --topic health --memory-type Preference --importance 8

2. Call it from agents and tools

cli-memory tools
cli-memory call store-memory '{"topicKey":"health","content":"Prefers warm water","memoryType":"Preference","importance":8}'
cli-memory call search-memories '{"topicKey":"health","query":"warm water","limit":5}'
cli-memory call supersede-memory '{"topicKey":"health","oldId":"mem_001","content":"The user now prefers cold water","memoryType":"Preference","importance":8}'

3. Review memories with the user

cli-memory review --topic health --limit 3
cli-memory reviewed mem_001 --topic health

review returns a small ranked batch of memories worth checking. It does not mutate memory content or usage stats. Use reviewed when the user confirms a memory is still correct.

4. Index documents

cli-memory doc index ./docs ./notes.md --topic api
cli-memory doc index https://example.com/guide --topic api
cli-memory doc search "cache invalidation" --topic api
cli-memory doc search "cache invalidation" --topic api --full

Supported local formats: txt, md, html, csv, docx.

5. Use the web console or REST API

cli-memory serve
curl http://127.0.0.1:3456/api/topics
curl http://127.0.0.1:3456/api/docs/collections

The built-in UI serves both consoles from one origin:

• / for memories
• /docs for document collections

Defaults you usually do not need to change

• Default embedding backend: local transformers
• Default model: onnx-community/embeddinggemma-300m-ONNX
• Default memory DB: ~/.config/cli-memory/memory-lancedb
• Default docs DB: ~/.config/cli-memory/docs-lancedb

On first run, the default model is downloaded locally and reused from cache. embeddingVersion is derived automatically from the active model/runtime, so it does not need manual configuration.

Legacy Ollama compatibility still works: set EMBEDDING_BACKEND=ollama or use legacy OLLAMA_* variables.

Daemon mode

Any running cli-memory serve process can be reused by later tool-backed CLI commands. serve --daemon is just the background form, so it is more convenient when an agent or script calls cli-memory repeatedly.

• transformers: the daemon keeps the local embedding runtime warm until idle unload
• ollama: the daemon still avoids repeated CLI startup overhead, but the model lifetime is owned by the external Ollama service

The CLI auto-detects a compatible running server from local metadata. CLI_MEMORY_DAEMON_URL is only needed when you want to force traffic to a specific daemon.

Agent skill

Install the bundled skill for a supported agent:

cli-memory skill install opencode

Also supported: claude, codex, copilot.

Common maintenance

cli-memory topic list
cli-memory reindex --topic health --mode stale
cli-memory migrate-schema --topic health
cli-memory reflect --topic health --save

If a topic or docs collection contains legacy or incompatible vectors, responses include compatibility details and a reindexHint.

Memory tiers

cli-memory now keeps one memory store with two logical tiers based on importance:

• 0-6: working
• 7-10: long-term

This keeps more short- and mid-term context available without mixing everything into durable memory. Use --tiers working or --tiers long-term on list and search when you want to narrow results.

retrieve-context prefers long-term by default and only pulls from working when it needs extra context.

History-preserving changes

When a fact or preference changed over time, use supersede instead of update.

• update: same memory, corrected wording
• merge: duplicate memories
• supersede: old memory was valid, but a newer memory is now current

Normal semantic search returns active memories by default, so superseded memories stay historical unless you explicitly ask for them with --status active,superseded. Generic store and update do not mark memories as superseded; that lifecycle transition is reserved for supersede. For ordinary current-state records, generic writes accept status values like active and completed.

Advanced docs

• Full CLI reference
• Server and REST API
• Embedding dimension behavior
• Multilingual retrieval design

Configuration

Most users do not need to touch configuration.

When you do, use environment variables or .env files. Full details and precedence rules are in docs/README.md.

Common variables:

| Variable | Default | Description | |---|---|---| | MEMORY_LANCEDB_URI | ~/.config/cli-memory/memory-lancedb | Memory database directory | | MEMORY_DOCS_LANCEDB_URI | ~/.config/cli-memory/docs-lancedb | Docs database directory | | EMBEDDING_MODEL | onnx-community/embeddinggemma-300m-ONNX | Local embedding model | | EMBEDDING_CACHE_DIR | ~/.cache/cli-memory/models | Download cache for local model files | | EMBEDDING_INACTIVITY_TIMEOUT_MS | 300000 | Idle unload timeout for the local daemon/runtime | | CLI_MEMORY_DAEMON_URL | (auto-detected) | Explicit daemon API base URL override | | MEMORY_API_KEY | (none) | REST API auth key |