Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Database management

The llm-mem db subcommand handles bank-level operations: export, import, merge, check, fix, rename, compact, prune.

db export

Export a bank to a portable .db file. The exported bank is ready for continued use — it’s a self-contained copy.

llm-mem db export --bank default --output backups/default.db
llm-mem db export --bank research --output research-portable.db --include-sessions
FlagTypeDescription
--bank <NAME>stringBank to export. Default: default.
--output <PATH>pathOutput file or directory.
--include-sessionsboolAlso copy the .sessions.db alongside.

db export-jsonl

Export a bank to a streaming JSONL text file. This format is backend-independent — a JSONL export from VectorLite can be imported into LanceDB and vice versa.

llm-mem db export-jsonl --bank default --output default.jsonl
llm-mem db export-jsonl --bank research --output research.jsonl --include-sessions

The JSONL file has:

  • An envelope header with format version, app version, embedding dimension, and config snapshot
  • One memory object per line in the body
  • A checksum footer

This makes it the safest format for archival and cross-backend migration.

db import

Import memories from a JSONL file into a bank.

llm-mem db import --bank default --input default.jsonl
llm-mem db import --bank default --input default.jsonl --dry-run    # preview only
llm-mem db import --bank default --input default.jsonl --strip-embeddings
FlagTypeDescription
--bank <NAME>stringTarget bank.
--input <PATH>pathThe JSONL file.
--strip-embeddingsboolDon’t import the embedding vectors; re-embed on import. Use when the new model has a different dimension.
--dry-runboolShow what would be imported without modifying anything.

The importer auto-handles dimension mismatches: if the JSONL has dimension 384 but your current model is 768, it’ll strip the old vectors and mark memories for re-embedding.

db merge

Merge one or more source banks (or .db files) into a target bank.

llm-mem db merge --source research --source notes --into combined --on-duplicate keep-newest
llm-mem db merge --source old-backup.db --into default --on-duplicate keep-first
llm-mem db merge --source a.lance --source b.lance --into merged --dry-run
FlagTypeDefaultDescription
--source <NAME_OR_PATH>string[]requiredRepeatable. Bank names or .db file paths.
--into <NAME>stringrequiredTarget bank name (created if missing).
--on-duplicate <STRATEGY>stringkeep-newestkeep-newest, keep-first, or keep-all.
--dry-runboolfalseShow what would be merged.

Duplicate detection uses content hash.

db check

Scan for consistency issues.

llm-mem db check --bank default
llm-mem db check --all
llm-mem db check --bank research --verbose
llm-mem db check --file external.db
FlagTypeDescription
--bank <NAME>stringSpecific bank.
--file <PATH>pathCheck an external .db file.
--allboolCheck every bank.
--verboseboolDetailed issue info.

Detects:

  • Orphaned abstractions (L1+ with no L0 source)
  • Stale state (sessions stuck in processing past their timeout)
  • Missing embeddings
  • Hash mismatches
  • Unreferenced forgotten memories
  • Duplicate content
  • Invalid layer structure

db fix

Repair detected issues.

llm-mem db fix --bank default --dry-run                    # preview
llm-mem db fix --bank default                              # fix all
llm-mem db fix --bank default --fix orphaned-abstractions  # fix specific types
llm-mem db fix --bank default --no-backup                  # skip auto-backup
llm-mem db fix --bank default --purge                      # hard-delete unreferenced Forgotten
FlagTypeDefaultDescription
--bank <NAME>stringdefault
--fix <TYPE>string[](all)Specific issue types. Valid: orphaned-abstractions, stale-states, missing-embeddings, hash-mismatches, unreferenced-forgotten, duplicate-content, invalid-layer-structure.
--dry-runboolfalseShow what would be fixed.
--no-backupboolfalseSkip automatic backup before fixing.
--purgeboolfalseHard-delete unreferenced Forgotten memories (vs. just marking them).

Warning

db fix is destructive for unreferenced-forgotten memories (with --purge) and for invalid-layer-structure. Always run with --dry-run first. The default behavior (without --no-backup) is to take a backup automatically.

db rename

Atomic rename of a bank. Moves both the memory database and the session database.

llm-mem db rename --old-name foo --new-name bar

db compact

Merge a bank’s small LanceDB fragments into larger ones for faster reads, and prune superseded versions. Compaction runs automatically every few writes, but this command forces it on demand.

llm-mem db compact --bank default
llm-mem db compact --all
FlagTypeDefaultDescription
--bank <NAME>stringdefaultSpecific bank.
--allboolfalseCompact every bank.

Compaction also triggers a safe prune (versions older than 7 days), so it reclaims disk space from accumulated old snapshots.

db prune

Delete old LanceDB dataset versions from disk to reclaim space.

LanceDB is copy-on-write: every add, update, delete, and compaction creates a new version snapshot and leaves the old version’s files in place. Without pruning, these superseded versions accumulate forever, causing unbounded disk bloat. This command deletes versions older than the cutoff.

# Reclaim all reclaimable space from a single bank (safe default)
llm-mem db prune --bank old-data

# Prune every bank
llm-mem db prune --all

# Keep the last 7 days of versions
llm-mem db prune --bank default --older-than-days 7

# Aggressive: also remove unverified files newer than 7 days (see warning)
llm-mem db prune --all --delete-unverified
FlagTypeDefaultDescription
--bank <NAME>stringdefaultSpecific bank.
--allboolfalsePrune every bank.
--older-than-days <N>integer0Keep versions newer than this many days. 0 removes everything eligible.
--delete-unverifiedboolfalseAlso delete files newer than 7 days that can’t be verified as committed.

Warning

--delete-unverified is only safe when no other process is reading or writing the dataset (e.g. the MCP server is stopped). Otherwise the dataset may be corrupted. Without this flag, LanceDB never deletes files newer than 7 days regardless of --older-than-days, so the default is always safe.

Tip

A safe one-off cleanup of bloated old databases:

llm-mem db prune --all --older-than-days 0

Common workflows

Migrate a bank to a new machine

# Source
llm-mem db export --bank default --output default.db --include-sessions
# scp default.db new-host:

# Destination
llm-mem db export --bank default --output /tmp/backup.db  # safety backup
# (stop the server, place default.db in the banks_dir, restart)

Cross-backend migration (e.g. VectorLite → LanceDB)

# Export as backend-independent JSONL
llm-mem db export-jsonl --bank old --output migration.jsonl

# On the new system with LanceDB configured:
llm-mem db import --bank new --input migration.jsonl

Recover from corruption

llm-mem db check --all --verbose                # identify
llm-mem db fix --bank default --dry-run         # preview
llm-mem db fix --bank default                   # repair (auto-backup)

If db fix can’t repair, restore from a backup created via backup_bank (MCP) or db export.

Next