remembrane
Local-first SQLite memory store CLI for AI agents
TLDR
SYNOPSIS
remembrane [--db path] subcommand [options] [args]
DESCRIPTION
remembrane is a command-line interface for inspecting and managing a local-first agent memory store backed by a single SQLite file. The same package also exposes a Python API, framework adapters (LangChain, CrewAI), and an optional MCP server entry point (remembrane-mcp).Memories are stored with optional namespaces and importance scores. recall ranks candidates with a hybrid of vector similarity and BM25 keyword score, plus recency decay, importance, and usefulness learned from task-outcome feedback. Ranking is exact (brute-force over the store) rather than approximate nearest-neighbor; the default embedder is a pure-stdlib hash embedder so pip install remembrane needs no extra dependencies.Every store, forget, and reinforce operation is journaled, so snapshot, diff, and log support time-travel over what the agent knew. conflicts surfaces contradictory memories for adjudication instead of silently picking one. pack selects an optimal (or near-optimal without numpy) memory set under a token budget. merge absorbs another memory database with near-duplicate deduplication.
PARAMETERS
--db path
Path to the SQLite memory database (default: remembrane.db).store [content] [--file path|-] [--namespace ns] [--importance f]
Store a memory. Provide content as an argument, or use --file (or --file - for stdin) for large payloads that hit OS argv limits.recall query [--namespace ns] [-k n] [--mode hybrid|vector|keyword] [--explain]
Recall top memories for query. --explain prints the ranking breakdown per result.list [--namespace ns]
List stored memories (optionally filtered by namespace).forget memoryid_
Delete one memory by id.export [--namespace ns]
Export memories as JSON to stdout.stats
Print memory counts overall and per namespace.snapshot label
Record a named point in the journal for later diff / reconstruction.log [--namespace ns] [--limit n]
Show newest-first history of operations (default limit 30).diff a [b]
Show what changed between snapshot a and snapshot b (or now if b is omitted).conflicts [query] [--namespace ns] [--min-confidence possible|likely]
Surface memories in tension (heuristic conflict detection).feedback memoryid_ --useful|--useless
Record task-outcome feedback that adjusts usefulness ranking.pack query [--budget tokens] [--namespace ns]
Select memories that fit a hard token budget for context packing.merge source.db [--dedupe-threshold f]
Merge another memory database into the current one.
CAVEATS
The CLI writes wherever --db points with the invoking user's permissions; it is a local tool, not a sandbox. The default embedder is lexical (n-gram hashes), not semantic—plug in optional embedders for true semantic recall, and do not mix embedders in one database. Conflict detection is heuristic: treat likely / possible hits as candidates for the agent or user to adjudicate. WAL mode keeps transient -wal / -shm sidecars next to the db file; avoid placing memory files on NFS/SMB. For MCP use, install remembrane[mcp] and run remembrane-mcp separately.
HISTORY
remembrane is an open-source Python project for local agent memory without a vector-database dependency. Public releases on PyPI (0.4–0.5.x series) refined hybrid recall, conflict signals, usefulness feedback, and packing; the console scripts remembrane and remembrane-mcp ship with the package.
