CLI reference

Ten commands. Every one of them is a local read except the four that write into a folder you name.

crossmem help <command> prints the same detail in your terminal, and crossmem --version reports the build metadata stamped in at release.

scan

Discovers known local context stores without reading any transcript contents. The first thing to run when something looks missing.

crossmem scan
crossmem scan --json

list [folder]

Lists local sessions, most recent first. Pass a folder — positionally or with --folder — to show only sessions whose real working directory is that folder, across all tools.

Each row carries the agent, how long ago it ran (“15 hours ago”), the local date/time, and the first and last question, so you can confirm which session to load before paying to load it.

crossmem list --limit 5                    # 5 most recent across all tools
crossmem list . --limit 5                  # 5 most recent for THIS folder
crossmem list --provider claude --limit 20
crossmem list /path/to/repo --json

OpenCode subagent sessions are folded into the session that spawned them — the parent's JSON carries their refs as children — so the list shows the work you did, not every helper it ran.

load [folder]

Prints a portable context bundle: a header, the guardrails block, then a bounded excerpt per session. The CLI extracts readable recent history and references the active instruction files; the consuming agent decides whether to summarize or ask for more.

crossmem load .
crossmem load . --limit 1                  # latest session, summary
crossmem load . --limit 1 --full           # latest session, fuller excerpt
crossmem load --session /path/to/session.jsonl --full
crossmem load --session devin:1a2b3c --full
crossmem load . --out .crossmem/context.md

--full raises the per-session budget from 9,000 to 24,000 characters. When a session does not fit, the bundle says so honestly rather than silently truncating: it keeps the opening — which states the goal — then an [... middle of the session elided ...] marker, then the most recent turns, which is where the work actually stopped. A single over-long turn (usually a pasted file) ends with ...[N chars trimmed]. Treat both markers as real.

Tired of typing --full? crossmem config --init, then "defaults": {"mode": "full"}.

update [folder]

The durable form of a bundle. Writes <folder>/.crossmem/:

crossmem update .
crossmem update /path/to/repo --provider claude --limit 5 --full

guardrails [folder]

Prints the instruction files an agent must read before acting: AGENTS.md, CLAUDE.md, .agents/AGENTS.md, .claude/CLAUDE.md. load and update already embed this block in their bundles.

crossmem guardrails .

These are authoritative. Session transcripts are context only. A decision found in a transcript that contradicts a guardrail file loses.

export [folder]

Writes one qa.jsonl of every question, the full answer, and everything that happened in between — tools, results, thinking. No agent name, no model name, no tokens. This is the only export format, and import reads the same file back.

crossmem export .                    # this folder → .crossmem/qa.jsonl
crossmem export --out ~/conversations # whole machine
crossmem export --provider claude --json

Each line:

{"sessionId":"…","folder":"/path","q":"…","a":"…","time":"…",
 "messages":[{"role":"user","content":"…"},
             {"role":"assistant","content":"…"},
             {"role":"tool","name":"Write","content":"…"}]}

Reach for it when you want a training corpus, a RAG corpus, or to carry conversations to another machine. --out is a destination directory.

import [folder]

Reads a qa.jsonl written by export. --in may be the file itself or a directory containing one.

crossmem import --in ~/conversations              # into dumpDir
crossmem import . --in ~/conversations            # into ./.crossmem/qa.jsonl
crossmem import . --in ~/conversations --merge --dry-run

--merge appends pairs not already in the destination; --dry-run reports counts without writing. Always dry-run first when the destination already holds a corpus.

sync

Mirrors a store dump — the original transcripts — between machines using the rclone binary on PATH. Separate from export/import, which move a conversation corpus.

crossmem sync --remote hetzbox:companydata/convdump
crossmem sync --pull --remote hetzbox:companydata/convdump
crossmem sync --prune            # rclone sync: delete extras at the destination

Set a standing remote instead of typing it every time:

{ "dumpDir": "~/.assets/convdump",
  "sync": { "remote": "hetzbox:companydata/convdump" } }

The dump applies the same secret filter as everything else — auth, credential, env and key material plus vault/, cache and node_modules directories never leave the machine.

config

Shows the config file location and, for every store, the paths crossmem looks in on this machine and which of them exist. It is how you check a store was found and learn the exact key to override.

crossmem config
crossmem config --init     # write a starter file

Details and the full override syntax are on the stores page.

install --skills / uninstall --skills

Both are escape hatches: crossmem installs the bundled crossmem-loader skill by itself, on the first command after an install or an upgrade (and in npm's postinstall). Use these to force it, to target one host, or to opt out.

crossmem install --skills             # ~/.claude/skills, plus ~/.agents/skills when codex is on PATH
crossmem install --skills --agents    # both, always
crossmem uninstall --skills --agents  # remove it, and stop it coming back

The install is atomic — temp dir, then rename — so a reader never sees a half-written skill and a failed install leaves the old copy intact. Uninstalling also disables the automatic install, and CROSSMEM_NO_SKILL_INSTALL=1 skips it for one run. It never creates repo-local skill folders. What the skill does →

Debugging a run

CROSSMEM_DEBUG=1 crossmem scan
CROSSMEM_LOG=/tmp/crossmem.log crossmem load . --limit 5

Logs include command flow and local read/query failures — never transcript contents. Because active agents may be writing these files while you read them, file and SQLite reads retry up to three times with small backoff, only on transient errors (“database is locked”, “busy”), never on missing-file or permission errors. SQLite opens are read-only with a busy timeout.