Samantha LLM — Persistent Memory for AI Assistants

Documentation and website for samantha-llm

View on GitHub

CLI Reference

Complete command reference for the samantha-llm CLI.

Sessions

start

Start an AI assistant session.

samantha-llm start                     # Use default agent and persona
samantha-llm start abacus              # Use a specific agent
samantha-llm start --persona devops    # Use a specific persona

Creates a temporary .ai-cerebrum symlink in the current directory, launches your agent with the bootstrap prompt, and cleans up when the session ends.

link / unlink

Manually manage the workspace symlink.

samantha-llm link       # Create persistent .ai-cerebrum symlink
samantha-llm unlink     # Remove it

Use link for long-running projects where you want the symlink to survive across sessions. When a manual link exists, start skips auto-linking.

Setup & Configuration

install / uninstall

samantha-llm install      # Set up config directory and PATH entry
samantha-llm uninstall    # Remove installation (optionally keeps config)

setup

Configure an agent interactively.

samantha-llm setup                   # Add a new agent (interactive)
samantha-llm setup --default claude  # Change the default agent

Supports Claude Code, Abacus.ai, GitHub Copilot, and custom agents.

status

Show installation and configuration summary.

samantha-llm status

Displays installation path, config location, configured agents, and default settings.

agents

List all configured agents.

samantha-llm agents

version

samantha-llm version

Personas

personas

List registered personas and manage the default.

samantha-llm personas                            # List all
samantha-llm personas --set-default my-persona   # Change default

register-persona

Register a custom persona from a Markdown file.

samantha-llm register-persona my-persona ./persona.md
samantha-llm register-persona my-persona ./persona.md --description "DevOps specialist"

The file is copied into the config directory. The original is not modified.

unregister-persona

Remove a custom persona.

samantha-llm unregister-persona my-persona

Cannot unregister the builtin persona or the current default.

Requires QMD to be installed.

memories index

Index memory files for semantic search.

samantha-llm memories index

Indexes all Markdown files across short-term memory, long-term memory, current tasks, and work experience. Incremental — only changed files are re-indexed.

Search across all memories.

samantha-llm memories search "deployment strategy"
samantha-llm memories search "auth decision" --json
samantha-llm memories search "CI pipeline" --text

Uses hybrid search (keyword + semantic + AI re-ranking) by default.

QMD Management

qmd install

Install the QMD search engine and Bun runtime.

samantha-llm qmd install

AI models (~2GB) download automatically on first use.

qmd install-bun

Install only the Bun runtime.

samantha-llm qmd install-bun

qmd status

Show QMD installation details — Bun status, QMD status, downloaded models.

samantha-llm qmd status

qmd check

Quick availability check (exit code 0 if installed).

samantha-llm qmd check

Subconscious (Session Processing)

The subconscious system runs automatically after each session. These commands are for monitoring and troubleshooting.

subconscious status

Check whether a background worker is running and if sessions are awaiting merge.

samantha-llm subconscious status

subconscious merge

Integrate processed session memories into your memory system.

samantha-llm subconscious merge

Run this after the background worker finishes — or let your assistant prompt you during the next session.

subconscious list

List all session workspaces and their processing status.

samantha-llm subconscious list

subconscious retry

Retry failed chunks from an interrupted session.

samantha-llm subconscious retry <session_id>

Picks up where it left off — completed chunks are not reprocessed.

subconscious reprocess

Reprocess sessions that produced empty results.

samantha-llm subconscious reprocess              # All empty sessions
samantha-llm subconscious reprocess <session_id>  # Specific session

subconscious wait

Block until the background worker finishes.

samantha-llm subconscious wait

subconscious guidance

Show the analysis guidance from the most recent session.

samantha-llm subconscious guidance

subconscious reset-prompt

Reset the analysis prompt to the default.

samantha-llm subconscious reset-prompt

Quick Reference

Task Command
Start a session samantha-llm start
Check status samantha-llm status
Add an agent samantha-llm setup
Search memories samantha-llm memories search "query"
Index memories samantha-llm memories index
Merge session memories samantha-llm subconscious merge
Register a persona samantha-llm register-persona name file.md
Install QMD samantha-llm qmd install

Next Steps