Memory System

Overview

The memory system is plugin-based. A memory.Provider interface in pkg/memory/ defines the contract, and concrete implementations live in plugins/memory/. Two built-in plugins ship with anna:

Switching Plugins

Memory plugins are managed like other plugins. In the admin panel or via anna plugin:

anna plugin disable memory/lcm
anna plugin enable memory/simple

Only one memory plugin should be enabled at a time. Both use the same underlying ctx_messages table, so switching preserves stored messages.

Provider Interface

The core Provider interface (pkg/memory/provider.go) has 5 methods:

Optional Capabilities

Providers can implement additional interfaces detected via type assertion:

The LCM plugin implements all 7 interfaces. The Simple plugin implements Provider, ProfileStore, and SessionManager.

Tool Auto-Generation

memory.BuildTool(provider) inspects the provider's capabilities and generates a tools.Tool with matching actions:

The tool's JSON schema, description, and dispatch all adapt dynamically. A provider with fewer capabilities produces a tool with fewer actions.

LCM Plugin

Architecture

ai.Message (user/assistant/tool_result)
        |
        v
  +----------+     Append     +-----------+
  | Provider  | ------------> | SQLite DB |
  +----------+                +-----+-----+
     |    |                          |
     |    | Compact                  |  Tables:
     |    v                          |    ctx_conversations
     | +------------------+          |    ctx_messages
     | | CompactionEngine | <--------+    ctx_summaries
     | +------------------+          |    ctx_items
     |                               |    ctx_summary_messages
     |  Assemble (budget)            |    ctx_summary_parents
     v                               |
  +------------+                     |
  | Assembler  | <-------------------+
  +------------+
        |
        v
  []ai.Message (fresh tail + summaries within token budget)
        |
        v
  LLM context window

Compaction

Compaction reduces the context window by summarizing older messages and summaries.

Modes:

Passes:

1. Leaf pass — Groups contiguous runs of message context items outside the fresh tail. Groups of 10+ messages are summarized into a leaf summary (depth 0).
2. Condensed pass — Groups contiguous runs of summary context items at the same depth. Groups of 2+ summaries are condensed into a condensed summary at depth+1.

Summarization escalation:

1. Normal mode — Preserves key decisions, rationale, constraints. Target: input_tokens/3.
2. Aggressive mode — Keeps only durable facts. Triggered when normal exceeds 150% of target.
3. Deterministic fallback — Truncates at sentence boundary. Triggered when aggressive still exceeds 150%.

Context Assembly

1. Separate context items into fresh tail (last N message items, default 20) and older items.
2. Resolve fresh tail items to ai.Messages — always included regardless of budget.
3. Fill remaining budget with older items, newest first.
4. Return older events (chronological) + tail events.

Concurrency

• Per-session mutex — Append and Compact acquire a per-session lock to prevent concurrent mutations.
• Conversation ID cache — Immutable sessionID -> convID mapping cached after first lookup.

Simple Plugin

The Simple plugin uses a sliding-window approach:

1. Append stores messages in ctx_messages (same schema as LCM).
2. Assemble returns the last N messages that fit within the token budget, always honoring freshTail.
3. No summaries, no compaction, no search, no explore.

This is suitable for short-lived conversations or resource-constrained environments.

Database

• Location: ~/.anna/anna.db
• Driver: modernc.org/sqlite (pure Go, no CGO)
• Mode: WAL, foreign keys enabled
• Migrations: Atlas-generated, embedded via MigrationsFS, auto-applied on startup.

Schema:

Configuration Defaults

Identity & User Memory

3-Layer System Prompt

User Memory

User memory is stored in ctx_agent_memory, keyed by (user_id, agent_id). The agent updates it via the memory tool's profile_update action and reads it via profile_get.

Agent Workspaces

Each agent has its own workspace at $ANNA_HOME/workspaces/{agent_id}/ for file overrides, skills, and per-agent data.