mempalace/website/reference/cli.md

CLI Commands

All commands accept --palace <path> to override the default palace location. The top-level command also accepts --backend <name> to select a storage backend such as sqlite_exact, milvus, qdrant, or pgvector.

mempalace init

Scan a project directory for people, projects, and rooms, and set up the palace.

mempalace init <dir>                 # <dir> is required
mempalace init <dir> --yes           # non-interactive mode
mempalace init ~/projects/myapp      # example
mempalace init .                     # initialize from the current directory

Option	Description
<dir>	Required. Project directory to scan. Pass . for the current directory.
--yes	Auto-accept all detected entities

What it does:

1. Scans <dir> for people and projects in file content
2. Detects rooms from <dir>'s folder structure
3. Saves detected entities to <dir>/entities.json
4. Ensures the global ~/.mempalace/ config directory exists

Running mempalace init with no argument will exit with error: the following arguments are required: dir.

mempalace mine

Mine files into the palace.

mempalace mine <dir>
mempalace mine <dir> --mode convos
mempalace mine <dir> --mode convos --extract general
mempalace mine <dir> --wing myapp

Option	Default	Description
<dir>	—	Directory to mine
--mode	projects	projects for code/docs, convos for chat exports
--wing	directory name	Wing name override
--agent	mempalace	Agent name tag
--limit	0 (all)	Max files to process
--dry-run	—	Preview without filing
--extract	exchange	exchange or general (for convos mode)
--no-gitignore	—	Don't respect .gitignore
--include-ignored	—	Always scan these paths even if ignored

mempalace search

Find anything by semantic search.

mempalace search "query"
mempalace search "query" --wing myapp
mempalace search "query" --wing myapp --room auth
mempalace search "query" --results 10

Option	Default	Description
"query"	—	What to search for
--wing	all	Filter by wing
--room	all	Filter by room
--results	5	Number of results

mempalace split

Split concatenated transcript mega-files into per-session files.

mempalace split <dir>
mempalace split <dir> --dry-run
mempalace split <dir> --min-sessions 3
mempalace split <dir> --output-dir ~/split-output/

Option	Default	Description
<dir>	—	Directory with transcript files
--output-dir	same dir	Write split files here
--dry-run	—	Preview without writing
--min-sessions	2	Only split files with N+ sessions

mempalace wake-up

Show L0 + L1 wake-up context (~600–900 tokens).

mempalace wake-up
mempalace wake-up --wing driftwood

Option	Description
--wing	Project-specific wake-up

mempalace compress

Compress drawers using AAAK Dialect.

mempalace compress --wing myapp
mempalace compress --wing myapp --dry-run
mempalace compress --config entities.json

Option	Description
--wing	Wing to compress (default: all)
--dry-run	Preview without storing
--config	Entity config JSON file

mempalace status

Show what's been filed — drawer count, wing/room breakdown.

mempalace status

mempalace repair

Rebuild palace vector index from stored data. Fixes segfaults after database corruption.

mempalace repair

Creates a backup at <palace_path>.backup before rebuilding.

mempalace mcp

Helper command that outputs setup syntax (like claude mcp add...) to connect MemPalace to your AI client, automatically handling paths.

mempalace mcp
mempalace mcp --palace ~/.custom-palace

mempalace hook

Run hook logic for Claude Code / Codex integration.

mempalace hook run --hook stop --harness claude-code
mempalace hook run --hook precompact --harness claude-code
mempalace hook run --hook session-start --harness codex

Option	Values	Description
--hook	session-start, stop, precompact	Hook name
--harness	claude-code, codex	Harness type

mempalace instructions

Output skill instructions to stdout.

mempalace instructions init
mempalace instructions search
mempalace instructions mine
mempalace instructions help
mempalace instructions status

mempalace logstream

Agent coordination events — delegate work, wait for replies, acknowledge outcomes (RFC 003). Operates on logstream.sqlite3 in the palace directory; safe to run alongside a live hub. See Agent Logstream.

mempalace logstream append --type task.request --stream project/myapp \
  --room delegation --from-agent mac --to-agent windows \
  --correlation-id task_123 --body "Please fix the flaky test."

mempalace logstream list --stream project/myapp --room delegation --json
mempalace logstream wait --correlation-id task_123 --type patch.ready \
  --timeout-ms 300000 --json
mempalace logstream ack evt_... --from-agent mac --status applied

Subcommand	Description
append	Append an immutable event (--type, --stream, --room, --from-agent required; --body/--body-file, --artifact-id repeatable)
list	List events, oldest first (all routing fields as filters, --since-event-id, --limit)
wait	Long-poll until a match or timeout (--timeout-ms, max 300000; exits 2 on timeout)
ack	Append an event.ack for an event (--from-agent required, --status, --body)
sync	Pull missing events/artifacts from peer replicas (--peer URL --token T, or all peers in peers.json)

All subcommands accept --json for scriptable output.

mempalace artifact

Exact artifact exchange for agent handoffs — unified diffs, files, logs. Content is stored verbatim with a SHA-256.

git diff | mempalace artifact put --kind patch --created-by windows --json
mempalace artifact get art_... | git apply --3way
mempalace artifact get art_... --out /tmp/handoff.patch

Subcommand	Description
put	Store content (--kind patch|file|log|json|note, --created-by required; --content, --file, or stdin)
get	Print exact content to stdout, or --out FILE; --json for metadata

mempalace replica

Memory replication across your machines (RFC 004; see The Replicated Palace). Bootstraps a new replica from its peers and moves precomputed vectors between machines.

# Bootstrap: fold every peer's authored content into this palace.
# STOP the local hub first — this writes the palace directly.
mempalace replica pull --with-vectors

# One specific origin instead of peers.json:
mempalace replica pull --peer https://desktop.example.com --token "$TOKEN"

# Precompute vectors into the portable cache (safe alongside a live hub):
mempalace replica embed-cache --batch 512 --json

Subcommand	Description
pull	Fold drawers + knowledge graph from origins (--peer/--token or peers.json; --with-vectors uses origin-precomputed vectors, --no-kg, --no-reconcile)
embed-cache	Bulk-embed local content into vector_cache.sqlite3 so peers can pull --with-vectors (--model, --batch, --all)

pull requires the local hub to be stopped (single-writer rule) and the origins to be quiescent (no active mines). Pulls are insert-only and resumable — re-running heals any gap. Raise MEMPALACE_SYNC_HTTP_TIMEOUT (seconds, default 30) for large bootstraps.

A running hub syncs the logstream automatically every MEMPALACE_SYNC_INTERVAL seconds (default 15). The CLI verbs exist for bootstraps, offline machines, and inspection.

::: tip Full convergence is staged mempalace replica pull gives you read replicas: a one-way fold of drawers and graph facts from an origin. Bidirectional convergence — where every replica is an equal writer and edits merge automatically — is RFC 004 step 2a (the memory op-log), staged for a later release. Until then, treat each replica's own captures as authoritative locally and pull from the origins that hold what you want mirrored. :::