Skip to content

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 TypeWhat It StoresAccess PatternPurpose
ConversationalUser and assistant message turns for the current sessionSequential (recent history)Maintain conversation continuity within a session
SemanticVector embeddings of past interactions and documentsSimilarity search (nearest neighbor)Recall relevant past information from the same session (filtered by session_id since core 0.71.0)
EpisodicStructured event logs (tool calls, decisions, outcomes)Filtered query (by type, time, agent)Track what the agent did and why, audit trail

Each memory type supports multiple storage backends:

BackendIdentifierDescription
RedisredisPersistent across restarts, TTL support, shared across instances. The only one the factory builds.
BackendIdentifierDescription
In-memorymemorySimple cosine similarity, no persistence
ChromaDBchromaEmbedded vector database, file-based persistence
PostgreSQL + pgvectorpgvectorProduction vector store with SQL integration
BackendIdentifierDescription
In-memorymemoryList-based, lost on restart
PostgreSQLpostgresDurable event log with timestamp indexing

Strategies control how conversational memory is read back. All of them read the last max_turns turns; the token budget below is then applied on top.

StrategyBehaviorConfiguration
sliding_windowKeep only the last max_turns turns. Oldest turns are droppedmax_turns: 20
summaryTurns that leave the max_turns window are folded into an incremental summary, kept next to the verbatim turnsmax_turns: 20
token_budgetKeep as many recent turns as fit the budget, newest firstmax_turns: 20

The engine calls fit_history(context, budget) after it has measured the rest of the prompt:

budget = 90% of context window − (system prompt + tool schemas + response max_tokens + prompts.context)

Turns are kept newest first until the budget is spent. A summary is counted first and dropped if it alone does not fit.

Window resolution, in order: context_window on the model candidate in the YAML, then parameters.num_ctx (Ollama), then litellm’s model info. With several candidates in the default role, the smallest window is used. If none resolves, the window is unknown: no budget trimming, only max_turns applies, and a warning is logged at load time.

Delivery. History reaches the model as chat messages (react and glyph patterns), so the system prompt stays identical between turns and the provider cache can work. If prompts.system references memory.conversation (detected by memory\.conversation\b), the legacy path is used instead: history is rendered into the system prompt, no messages are sent, and a warning is logged.

Token counts. persist_turn stores each turn with its token_count (litellm if installed, otherwise len/4). Old rows stored with 0 are estimated when read. Assistant replies over 50 tokens go to semantic memory when it is wired.

Summary. With strategy: summary, after the assistant turn of an exchange, once max_turns is exceeded, persist_turn makes one call to the agent’s summarizer role (or default) that merges the turns just leaving the verbatim window into the previous summary. It runs inline and a failure does not break persist_turn.

spec:
memory:
conversational:
backend: redis
strategy: sliding_window
max_turns: 20
semantic:
backend: faiss
dimension: 768
embeddings: {provider: ollama, model: nomic-embed-text}
episodic:
backend: postgres
connection: {url: "postgresql://user:pass@localhost:5432/astromesh"}

build_context(agent_name, session_id, query)

Section titled “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. Read the last max_turns turns (plus the running summary with summary). With max_tokens set, trim to it; without it nothing is trimmed here and the engine applies the budget later with fit_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:

FieldTypeDescription
historylist[Message]Trimmed conversational turns
semantic_resultslist[SemanticResult]Relevant past interactions (text + similarity score)
episodeslist[Episode]Recent event log entries

persist_turn(agent_name, session_id, user_message, assistant_message)

Section titled “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)

Delete all conversational history for a session.

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

Full memory configuration example:

spec:
memory:
conversational:
backend: redis
strategy: token_budget
max_turns: 20
connection:
url: "redis://localhost:6379/0" # required, no default
ttl: 86400 # default: 259200 (72h)
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"
FieldRequiredDefaultDescription
conversational.backendNo—redis. Omit to run without conversational memory
conversational.connection.urlWith redis—Redis URL. Read with no default
conversational.ttlNo259200Seconds a session’s history survives (72h)
conversational.strategyNosliding_windowRetention strategy
conversational.max_turnsNo50Turns read back per run; with summary, the verbatim window
semantic.backendNo—Backend for vector memory. Omit to disable semantic memory
semantic.collectionNo{agent_name}_memoryVector store collection name
semantic.top_kNo5Number of similar results to retrieve
episodic.backendNo—Backend for event logs. Omit to disable episodic memory
Built by FAiNANSU