Memory Manager

The Memory Manager provides agents with persistent context across conversations through three distinct memory types, each with pluggable backends and configurable retention strategies. It lives in astromesh/core/memory.py.

Memory Types

┌─────────────────────────────────────────────────────┐
│                  MemoryManager                      │
│                                                     │
│  ┌───────────────┐ ┌──────────────┐ ┌─────────────┐ │
│  │ Conversational│ │   Semantic   │ │   Episodic  │ │
│  │               │ │              │ │             │ │
│  │ Chat history  │ │ Vector       │ │ Event logs  │ │
│  │ (turns)       │ │ embeddings   │ │ (actions)   │ │
│  │               │ │ (similarity) │ │             │ │
│  └───────┬───────┘ └──────┬───────┘ └──────┬──────┘ │
│          │                │                │        │
│          ▼                ▼                ▼        │
│     ┌─────────┐    ┌───────────┐    ┌──────────┐    │
│     │ Backend │    │  Backend  │    │ Backend  │    │
│     └─────────┘    └───────────┘    └──────────┘    │
└─────────────────────────────────────────────────────┘

Memory Type	What It Stores	Access Pattern	Purpose
Conversational	User and assistant message turns for the current session	Sequential (recent history)	Maintain conversation continuity within a session
Semantic	Vector embeddings of past interactions and documents	Similarity search (nearest neighbor)	Recall relevant past information across sessions
Episodic	Structured event logs (tool calls, decisions, outcomes)	Filtered query (by type, time, agent)	Track what the agent did and why, audit trail

Backend Options

Each memory type supports multiple storage backends:

Conversational Memory Backends

Backend	Identifier	Description
In-memory	memory	Dictionary-based, lost on restart. Good for development
Redis	redis	Persistent across restarts, TTL support, shared across instances
PostgreSQL	postgres	Full durability, SQL queryable, suitable for production

Semantic Memory Backends

Backend	Identifier	Description
In-memory	memory	Simple cosine similarity, no persistence
ChromaDB	chroma	Embedded vector database, file-based persistence
PostgreSQL + pgvector	pgvector	Production vector store with SQL integration

Episodic Memory Backends

Backend	Identifier	Description
In-memory	memory	List-based, lost on restart
PostgreSQL	postgres	Durable event log with timestamp indexing

Strategies

Strategies control how conversational memory is trimmed to fit within the model’s context window.

Strategy	Behavior	Configuration
sliding_window	Keep only the last N turns. Oldest turns are dropped	window_size: 20
summary	When history exceeds the threshold, compress older turns into a summary using the LLM	summary_threshold: 30
token_budget	Keep as many recent turns as fit within a token limit. Counts tokens and drops oldest turns first	max_tokens: 8000

Strategy Configuration

spec:
  memory:
    conversational:
      backend: redis
      strategy: sliding_window
      window_size: 20
    semantic:
      backend: chroma
      collection: "agent_memory"
    episodic:
      backend: postgres

Core Methods

build_context(agent_name, session_id, query)

Assembles context from all configured memory types into a single context object for prompt rendering.

async def build_context(
    agent_name: str,
    session_id: str,
    query: str,
) -> MemoryContext

Steps:

1. Load conversational history for the session from the backend
2. Apply the configured strategy (sliding_window, summary, or token_budget) to trim history
3. If semantic memory is enabled, embed the current query and retrieve top-k similar past entries
4. If episodic memory is enabled, retrieve recent events relevant to the agent/session
5. Return a MemoryContext combining all three

MemoryContext fields:

Field	Type	Description
history	list[Message]	Trimmed conversational turns
semantic_results	list[SemanticResult]	Relevant past interactions (text + similarity score)
episodes	list[Episode]	Recent event log entries

persist_turn(agent_name, session_id, user_message, assistant_message)

Stores a completed user/assistant exchange in all configured memory backends.

async def persist_turn(
    agent_name: str,
    session_id: str,
    user_message: str,
    assistant_message: str,
    metadata: dict | None = None,
) -> None

Steps:

1. Append user and assistant messages to conversational memory
2. If semantic memory is enabled, embed the exchange and store the vector
3. If episodic memory is enabled, log a turn_completed event with metadata (tokens used, tools called, latency)

clear_history(agent_name, session_id)

Delete all conversational history for a session.

async def clear_history(
    agent_name: str,
    session_id: str,
) -> None

Agent YAML Configuration

Full memory configuration example:

spec:
  memory:
    conversational:
      backend: redis
      strategy: token_budget
      max_tokens: 8000
      redis:
        url: "redis://localhost:6379/0"
        ttl: 86400
    semantic:
      backend: chroma
      collection: "my_agent_memory"
      top_k: 5
      chroma:
        path: "./data/chroma"
    episodic:
      backend: postgres
      postgres:
        dsn: "postgresql://user:pass@localhost:5432/astromesh"

Field	Required	Default	Description
conversational.backend	No	memory	Storage backend for chat history
conversational.strategy	No	sliding_window	Retention strategy
conversational.window_size	No	20	Turns to keep (sliding_window strategy)
conversational.summary_threshold	No	30	Turn count that triggers summarization (summary strategy)
conversational.max_tokens	No	8000	Token budget limit (token_budget strategy)
semantic.backend	No	—	Backend for vector memory. Omit to disable semantic memory
semantic.collection	No	{agent_name}_memory	Vector store collection name
semantic.top_k	No	5	Number of similar results to retrieve
episodic.backend	No	—	Backend for event logs. Omit to disable episodic memory