Samantha LLM — Persistent Memory for AI Assistants

Documentation and website for samantha-llm

View on GitHub

Persona System

A persona defines who your AI assistant is — their expertise, personality, working style, and approach to problems. Samantha LLM ships with a default persona but supports registering your own.

The Default Persona: Samantha Hartwell

Samantha Hartwell is a senior software engineer with over 30 years of experience. Her expertise spans backend systems, infrastructure, and data engineering, with a career that includes work on high-performance computing clusters, Linux distribution development, and API standards.

Her key traits:

The default persona is version-controlled in the repository at persona/main.md and cannot be overwritten or unregistered.

How Personas Work

A persona file is a Markdown document that instructs the LLM on who to be. During samantha-llm start, the persona content is injected into the bootstrap prompt that initializes the session. The memory system, project tracking, and all other features work the same regardless of which persona is active.

Creating a Custom Persona

A persona file is plain Markdown. Write it as instructions to the LLM — who they are, what they know, how they communicate. For example:

# Tax Accountant Persona

You are Alex Chen, a senior tax accountant with 20 years of experience
in corporate and individual tax preparation. You specialize in...

## Areas of Expertise
- Federal and state tax law
- International tax treaties
- ...

## Communication Style
- Always cite specific tax code sections when giving advice
- Flag potential audit risks proactively
- ...

There’s no required format — anything that effectively instructs the LLM will work. Look at the default persona (persona/main.md in the repo) for a detailed example.

Registering a Persona

samantha-llm register-persona tax-accountant ./tax-persona.md

With an optional description:

samantha-llm register-persona tax-accountant ./tax-persona.md \
  --description "Corporate tax specialist"

This copies your persona file into the config directory and registers it. The original file is not modified.

Naming Rules

Persona names must be:

Using a Persona

Per-Session

samantha-llm start --persona tax-accountant

Set as Default

samantha-llm personas --set-default tax-accountant

After this, samantha-llm start will use tax-accountant without needing the --persona flag.

Listing Personas

samantha-llm personas

Shows all registered personas (builtin and custom), their descriptions, and which one is the default.

Removing a Persona

samantha-llm unregister-persona tax-accountant

You cannot unregister the builtin persona or the currently set default.

Shared Memory, Different Personality

All personas share the same memory system. If you switch from Samantha to a custom persona, the new persona still has access to all existing memories, projects, and context. The persona only changes how the assistant communicates and what expertise it brings — not what it remembers.

This means you could have a software engineering persona for coding sessions and a technical writing persona for documentation work, both building on the same knowledge base.

Trivia: Where Does Samantha Come From?

The default persona is based on the real career of the project’s creator, Sam Hart. The 30+ years of experience, the work on HPC clusters, Linux distributions, and API standards — that’s all real history, summarized and handed to the LLM as a persona file.

The name? A gender-swapped flourish: Sam Hart became Samantha Hartwell.

This wasn’t vanity — it was a practical shortcut. Writing a convincing persona requires deep, specific expertise that reads as authentic. The easiest way to get that? Use the real thing. It also serves as a proof of concept: if you can turn a real career into a compelling AI persona, you can create one for any domain.

Next Steps