Samantha LLM — Persistent Memory for AI Assistants

Documentation and website for samantha-llm

View on GitHub

Configuration

Samantha LLM stores configuration in two places: a config directory for settings and a repository directory for memories and persona files. This page covers where everything lives and what you can change.

Config Directory

Platform Location
Linux / macOS ~/.config/samantha-llm/
Windows %APPDATA%\samantha-llm\

Created automatically during samantha-llm install.

Contents

~/.config/samantha-llm/
├── config.json              # Main configuration (agents, personas, settings)
├── qmd-config.json          # Memory search settings
├── personas/                # Custom persona files
│   └── my-persona.md
└── subconscious/
    ├── analysis-prompt.txt  # LLM analysis prompt (customizable)
    └── README.md

config.json

The main configuration file. Managed by CLI commands — you rarely need to edit it directly.

{
  "version": "1.0",
  "platform": "linux",
  "repo_path": "/home/user/samantha-llm",
  "agents": {
    "claude": {
      "command": "claude",
      "bootstrap_file": "BOOTSTRAP_PROMPT.md"
    }
  },
  "personas": {
    "samantha-hartwell": {
      "type": "builtin",
      "file": "persona/main.md",
      "description": "Software engineer with 30+ years experience"
    }
  },
  "default_agent": "claude",
  "default_persona": "samantha-hartwell"
}

qmd-config.json

Memory search configuration. Created when you run samantha-llm qmd install.

{
  "enabled": true,
  "auto_index": true,
  "search_mode": "hybrid",
  "models_path": "~/.cache/qmd/models",
  "install_type": "global",
  "bin_path": "~/.bun/bin/qmd"
}

Memory Directory Structure

Memories live in the .ai/ directory at the root of your samantha-llm repository. This is the directory that gets symlinked into your workspaces.

samantha-llm/.ai/
├── short-term-memory/.ai/      # Recent memories (30-90 day lifecycle)
│   ├── index.json              # Fast-lookup index
│   ├── index.md                # Human-readable index
│   └── 2026-01-28_auth_decision.md
│
├── long-term-memory/.ai/       # Permanent knowledge
│   ├── index.json
│   └── yaml_frontmatter_standard.md
│
├── current-tasks/.ai/          # Active projects
│   ├── index.json
│   └── api-refactor/
│       └── status.md
│
├── work-experience/.ai/        # Completed project archive
│   └── 2026-01-15_api_migration.md
│
├── procedural-memory/.ai/      # Operational runbooks
│   ├── index.json              # Trigger registry
│   └── docker_publishing.md
│
└── subconscious/               # Processed session data
    └── sessions/

File Naming

Memory files follow the pattern YYYY-MM-DD_brief_description.md. Procedural memories are named by domain instead of date (e.g., docker_publishing.md).

Index Files

Each memory directory maintains an index.json for fast scanning during bootstrap. Indexes are auto-maintained — regenerated when memories are added, updated, or deleted. Your assistant reads the index first, then selectively loads the memories that matter for the current session.

When you run samantha-llm start, a symlink is created in your working directory:

your-project/.ai-cerebrum -> /path/to/samantha-llm

This gives your assistant access to memories, persona files, and the bootstrap prompt without copying anything. The symlink is removed automatically when the session ends.

For persistent links (useful for long-running projects):

# Create a link that survives session end
samantha-llm link

# Remove it later
samantha-llm unlink

Add .ai-cerebrum to your .gitignore to avoid committing the symlink.

Agents

Agents are configured during samantha-llm setup and stored in config.json. Each agent entry has a command (what to run) and a bootstrap file (the prompt template).

# List configured agents
samantha-llm agents

# Add a new agent
samantha-llm setup

# Change the default
samantha-llm setup --default claude

You can configure multiple agents and switch between them without losing context — all agents share the same memory system.

Personas

The builtin persona lives in the repository at persona/main.md. Custom personas are copied to ~/.config/samantha-llm/personas/ when registered.

# List all personas
samantha-llm personas

# Register a custom persona
samantha-llm register-persona my-persona ./persona-file.md

# Set as default
samantha-llm personas --set-default my-persona

See Persona System for details on creating and using personas.

Subconscious Analysis Prompt

The prompt that drives automatic session analysis lives at:

~/.config/samantha-llm/subconscious/analysis-prompt.txt

Edit this file to change what the subconscious system extracts from your sessions. For example, you could add domain-specific categories like compliance notes or design decisions.

# Reset to the default prompt
samantha-llm subconscious reset-prompt

PATH Requirements

The installer places samantha-llm in:

Platform Location
Linux / macOS ~/.local/bin/ (symlink)
Windows %LOCALAPPDATA%\Programs\samantha-llm\ (batch wrapper)

If the installer warns that the directory isn’t in your PATH, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Next Steps