cli-memory

Local-first, private long-term memory for AI agents. Everything runs on your machine — data never leaves your disk.

npm install -g cli-memory

Quick start

# Make sure Ollama is running with an embedding model (e.g. nomic-embed-text)
cli-memory store "The user prefers warm water" --topic health --memory-type Preference --importance 8
cli-memory search "warm water" --topic health
cli-memory serve  # http://127.0.0.1:3456 — web console + REST API

Why

LLM agents need durable, searchable long-term memory beyond the chat window. cli-memory gives every agent a local-first, topic-partitioned memory backend accessible via CLI, JSON-RPC (cli-memory call), REST API, or a built-in web admin console.

Your memories are stored in a local LanceDB database on your own disk. No cloud, no telemetry, no third party — not even for vector embeddings (Ollama runs locally). What you write stays yours.

Features

• 100% local-first — all data stays on your disk, zero cloud dependencies
• Topic-scoped — separate contexts (health, family, career) don't interfere
• Hybrid search — vector similarity + full-text search reranked by importance, recency, and access frequency
• Durable write gate — only importance >= 7 persists by default; avoids noise
• Memory lifecycle — extract, capture, merge, consolidate, reflect, prune
• Web admin console — browse, search, create, and edit memories from a built-in React UI
• Agent-ready — JSON output, cli-memory call interface, REST API, bundled agent skill

Requirements

• Node.js >= 18
• Ollama running locally with an embedding model (default: nomic-embed-text)
• A writable directory for LanceDB (default: ~/.config/cli-memory/memory-lancedb)

Configuration

Set any of these via environment variables or .env files (searched in order: $(pwd)/.env, then ~/.config/cli-memory/.env, then package fallback):

| Variable | Default | Description | |---|---|---| | MEMORY_LANCEDB_URI | ~/.config/cli-memory/memory-lancedb | LanceDB data directory | | OLLAMA_BASE_URL | http://127.0.0.1:11434 | Ollama server URL | | OLLAMA_EMBEDDING_MODEL | nomic-embed-text | Embedding model name | | MEMORY_API_KEY | (none) | REST API auth key |

Agent skill

Give any supported agent persistent long-term memory with one command:

cli-memory skill install opencode   # or: claude, codex, copilot

After installation, the agent automatically knows how to use cli-memory to store facts, recall past context, retrieve preferences, and manage memory topics — no manual prompting required. Restart the agent after installing.

Commands

cli-memory --help
cli-memory tools         # discover all machine-callable operations
cli-memory call store-memory '{"topicKey":"health","content":"Prefers warm water","importance":8}'
cli-memory topic list
cli-memory list --topic health --limit 10
cli-memory reflect --topic health --save

REST API

cli-memory serve                # http://127.0.0.1:3456 — web admin console + REST API
cli-memory serve -p 5000        # serve on port 5000
cli-memory serve --api-only     # REST API only, no UI
curl http://127.0.0.1:3456/api/topics

Docs

• Full CLI reference
• REST API reference