Memory Management

Last updated: April 11, 2026

Assistant Memory Management

Memory management in the assistant module is a sophisticated, multi-tiered system designed for long-term fact retention, semantic organization, and contextual awareness.

The 4-Tier Memory Hierarchy

The ProjectContextManager (in assistant/project_context.go) manages four distinct tiers of memory, each with different scopes and persistence:

  1. Tier 1: Short-Term (In-Memory)
    • Scope: Active session context.
    • Implementation: SessionContextManager.ShortTermCache.
    • Persistence: Cleared when the session ends.
  2. Tier 2: Project Workspace (memory.md)
    • Scope: Specific to an engineering or content project.
    • Implementation: A memory.md file within the project directory.
    • Persistence: Long-term, shared across all agents working on the project.
  3. Tier 3: User Global Memory (.global_memory/)
    • Scope: Global user-specific facts.
    • Implementation: Files in the user's .global_memory/ directory.
    • Persistence: Long-term, persists across all projects for a specific user.
  4. Tier 4: System Vault (vault.txt)
    • Scope: Global system-wide knowledge base and RAG.
    • Implementation: assistant/rag.go using Ollama embeddings and a local vault.
    • Persistence: Permanent system knowledge.

Fact Retention Models

The system employs several models for structuring memories:

  • WIS/WIH/WID Model: Standardized data model for:
    • (W)hat (I)s: Current state of the world/project.
    • (W)hat (I)s (H)appened: Log of significant events or changes.
    • (W)hat (I)s (D)one: List of completed tasks or milestones.
  • Significance [sig:1-5]: Every fact is weighted. Facts with high significance (4-5) are protected from pruning during reflection passes.

MemoryMaster Agent & Reflection Passes

The MemoryMaster agent (in assistant/conversation_intelligence.go) is a specialized persona that performs periodic "Reflection Passes" on chat logs and memory files.

The Reflection Workflow

  1. Ingestion: Reads the latest conversation logs and project memory.md.
  2. Distillation: Identifies new facts, task completions, and state changes.
  3. Evaluation: Assigns significance weights and determines if any existing facts should be pruned or merged.
  4. Update: Rewrites the memory files with high-signal data.

Key Functions

  • NewProjectContextManager(user, project string): Initializes a context manager for a specific workspace.
  • GetContext(tier MemoryTier): Retrieves content from a specific tier.
  • DistillMemories(user, agent string): Triggers a reflection pass for a user/agent pair.
  • SummarizeSession(session *ChatSession): Generates a high-level summary of a completed conversation.

Sequence Diagram: Memory Distillation

sequenceDiagram
    participant S as Scheduler
    participant MM as MemoryMaster Agent
    participant CP as chat_persistence.go
    participant PCM as project_context.go
    participant FS as File System

    S->>MM: Trigger Reflection Pass
    MM->>CP: Load Recent Chat Logs
    MM->>PCM: Load project memory.md
    MM->>MM: Distill Facts & Significance
    MM->>PCM: Update memory.md
    PCM->>FS: Atomic Write to File
    MM->>MM: Log Reflection Success

Guidance for AI Agents

  • Always check project memory: Before starting a task, read the memory.md to understand the current state.
  • Record high-signal facts: Use tools like record_fact or update_project_memory to persist important discoveries.
  • Significance matters: Explicitly mention if a fact is highly significant to ensure it survives the next reflection pass.

Cross-References