one-memory

CLI for AI memory: store memories under ~/.one-memory. All files go in memory-files/; index and metadata (including embeddings for semantic search) live in memory.db (SQLite). No categories; list/read/delete by id or filename. Run one-memory init once, then add/list/read/search/delete as needed.

Commands

| Command | Description | |---------|-------------| | init | Create root, memory-files/, and memory.db; optionally copy skills to agent dirs | | reset | Delete root and re-init (clean slate; for local dev) | | add | Add a memory (stdin or --file); generates local embedding for search | | list | List all memories; --tag to filter | | read <id> | Read one memory by id or filename | | search "query" | Semantic search (local embedding); only memories with embeddings are searched | | reindex | Backfill embeddings for memories that have none (e.g. added before embedding was enabled) | | delete <id> | Delete one memory (TTY: confirm; non-TTY: use --force) | | config get/set root | Get or set memory root path |

Config keys: root — memory root directory (default ~/.one-memory).

Search: Memories get an embedding on add. Old entries without embeddings are ignored by search until you run one-memory reindex.

Install

npm install -g one-memory

Note: SQLite is provided by sql.js (WASM, no native build), so yarn install / npm install does not require compilers or node-gyp.

Quick start

# Initialize ~/.one-memory (memory-files/ + memory.db) and optionally copy skills
one-memory init
one-memory init --skipSkills   # only create root, no skills prompt

# List all memories (from DB)
one-memory list
one-memory list --tag meeting  # filter by tag
one-memory list --json         # JSON output for scripts

# Add a memory (content from stdin or --file)
echo "Meeting notes" | one-memory add
one-memory add --file ./content.md
one-memory add note.md   # optional filename

# Read by id or filename
one-memory read meeting-notes-20250209100000
one-memory read meeting-notes-20250209100000.md

# Search by meaning (local embedding, no API)
one-memory search "meeting with John"
one-memory search "project ideas" -n 5

# Delete one memory
one-memory delete meeting-notes-20250209100000

Config

• root: memory root path (default ~/.one-memory).

one-memory config get root
one-memory config set root /path/to/memory

Layout

• ~/.one-memory/memory-files/ — all memory Markdown files
• ~/.one-memory/memory.db — SQLite index (id, file_path, title, created, tags, source, embedding) via sql.js. Embeddings are generated locally with @xenova/transformers (Xenova/all-MiniLM-L6-v2) on add; first run downloads the model (~80MB) and caches it.

Test commands (local dev)

From repo root (use node bin/run.js instead of one-memory before publish):

# Reset and init (clean state)
node bin/run.js reset --skipSkills

# Add a few memories (--file avoids stdin)
echo "Meeting with John about project Alpha." > /tmp/m1.txt
echo "Ideas: use SQLite and local embedding." > /tmp/m2.txt
node bin/run.js add --file /tmp/m1.txt --title "Meeting John"
node bin/run.js add --file /tmp/m2.txt --title "Tech ideas" --tags "idea,sqlite"

# List
node bin/run.js list
node bin/run.js list --tag idea

# Read by id (id from list output)
node bin/run.js read meeting-john-20250210120000

# Search by meaning
node bin/run.js search "discussion with John"
node bin/run.js search "database" -n 3

# Backfill embeddings for old entries (so search can find them)
node bin/run.js reindex

# Delete one
node bin/run.js delete meeting-john-20250210120000

More examples: docs/TEST_COMMANDS.md.

Requirements

See docs/REQUIREMENTS.md for the original spec. The current implementation uses a flat store (no categories), SQLite + local embeddings, and no move/merge; see docs/REVIEW.md for a feature review and what’s left to improve.