Samantha LLM — Persistent Memory for AI Assistants

Documentation and website for samantha-llm

View on GitHub

Memory System

Samantha LLM’s memory system is modeled after human memory — not a perfect transcript of everything, but a curated collection of what matters. Memories are structured, tagged, and prioritized so the right context surfaces at the right time.

Memory Types

Short-Term Memory

Recent interactions, decisions, and learnings. This is the working memory that keeps Samantha current on what you’ve been doing.

Short-term memories are actively pruned. Low-importance memories older than 30 days may be deleted. High-importance ones are promoted to long-term memory.

Long-Term Memory

Foundational knowledge and lessons learned that should persist indefinitely. These are refined, polished versions of the most important short-term memories.

Current Tasks

Active projects, their status, and working context. This is how Samantha knows what you’re working on and where things stand.

When you tell Samantha about a new project, she creates a task entry here. When a project completes, it moves to work experience.

Work Experience

Archive of completed projects. Samantha’s professional history — referenced when similar work comes up in the future.

Procedural Memory

Operational runbooks — compiled “how to do X” knowledge built from repeated sessions working in a specific domain. Unlike other memory types, procedural memories are named by domain rather than by date.

Critical Memories

Not a separate storage location — critical is a flag (critical: true) that can be set on any memory. Critical memories are read every session during bootstrap, regardless of age or topic. Use this sparingly for workflows that prevent costly mistakes.

Memory File Format

All memory files are Markdown with YAML frontmatter:

---
date: 2026-01-28
updated: 2026-02-15
topics: [testing, ci, automation]
importance: high
type: decision
project: api-gateway-refactor
reference_count: 5
---

# Decision: Use Modular Config for CI Pipeline

## Context
Why this decision was made...

## Key Points
- Important detail 1
- Important detail 2

## Follow-up
- [ ] Actions still needed

Frontmatter Fields

Field Required Values Purpose
date Yes YYYY-MM-DD When the memory was created
updated No YYYY-MM-DD Last update date
topics Yes [tag, ...] Categorization tags
importance No low, medium, high Priority for surfacing
type No See below What kind of memory
project No project name Associated project
reference_count No integer Times referenced across sessions
critical No true Must-read every session

Memory Types

How Memories Are Created

Memories come from three sources:

  1. Samantha creates them during sessions — When significant decisions are made, important context is shared, or projects are created. You can also ask her directly: “Please remember that we always use uv, not pip.”

  2. The subconscious system creates them automatically — After each session ends, a background worker analyzes the conversation and generates structured memory files. See Subconscious System.

  3. You create them manually — Memory files are just Markdown. You can create or edit them directly in the .ai/ directories.

Bootstrap: How Memories Are Loaded

When a session starts, Samantha reads memories in priority order:

  1. Critical memories — Everything flagged critical: true, every session
  2. High-priority memories — Frequently referenced (reference_count >= 5)
  3. Project-specific memories — Tagged with the current project
  4. Recent high-importance memories — importance: high from the last 30 days
  5. Procedural memory — Runbooks matching the current context
  6. Long-term memory — Accessed as needed during the session

This tiered approach ensures critical context is never missed while keeping startup fast.

Index Files

Each memory directory maintains an index.json (or index.md) for fast scanning. These are auto-maintained — regenerated when memories are added, updated, or deleted.

The index categorizes memories by importance, topic, and recency so Samantha doesn’t have to read every file during bootstrap. She reads the index first, then selectively reads the memories that matter for the current session.

Memory Lifecycle

New interaction or learning
        |
        v
  [Worth remembering?] --No--> Discard
        |
       Yes
        v
  Short-term memory (30-90 days)
        |
        v
  [Still relevant? Referenced often?]
        |             |
       Yes            No
        v              v
  Long-term memory   Delete
  (permanent)

Importance Escalation

As memories are referenced across sessions, their importance automatically escalates:

Next Steps