SuperOptiX Memory: A Practical Guide for Building Agents That Remember

Modern AI agents aren't just prompt-in, answer-out. To feel coherent and genuinely helpful over time, they need to remember. Agent memory is the capability that lets an agent retain facts, preferences, conversations, and experiences across turns and sessions—so every new interaction benefits from the history that came before it.

With memory, agents can personalize responses, maintain context across multi-step tasks, and learn from feedback. This is core to agentic systems, and it's why memory is a first-class feature in SuperOptiX.

SuperOptiX is a full-stack agentic AI framework designed for context and agent engineering with an evaluation-first, optimization-core philosophy. The framework's declarative DSL, SuperSpec, lets you describe what you want and have SuperOptiX build the pipeline.

What is Agent Memory?

Conceptually, memory is how agents build "continuity of self." Concretely, it's a combination of mechanisms that store and retrieve useful information:

This layered design balances immediacy (short-term), durability (long-term), chronology (episodic), and precision (context management). The result is an agent that feels consistent, learns from experience, and remains efficient.

How SuperOptiX Memory Works

SuperOptiX provides a powerful, multi-layer memory model you can use via Python, via DSPy adapters configured with JSON-like configs, or declaratively through SuperSpec (YAML).

Use Memory from Python (Public API)

Below are usage-only examples for working with memory in your own Python code.

from superoptix.memory import AgentMemory, FileBackend, SQLiteBackend
# RedisBackend is also available if you install and configure redis

# Create an agent memory (defaults to SQLite)
memory = AgentMemory(agent_id="writer-assistant")

# Short-term: store ephemeral context
memory.remember("User prefers TypeScript", memory_type="short", ttl=3600)

# Long-term: store durable knowledge with categories/tags
memory.remember(
    "Always provide runnable code snippets",
    memory_type="long",
    category="authoring_guidelines",
    tags=["writing", "code", "quality"]
)

# Recall (semantic search if embeddings are enabled)
results = memory.recall("runnable code", memory_type="long", limit=5)
for r in results:
    print(r["content"])

# Track an interaction episode with events
episode_id = memory.start_interaction({"user_id": "alice"})
memory.add_interaction_event("user_question", "How to configure memory backends?")
# ... generate your response ...
memory.end_interaction({"success": True})

# Introspection and housekeeping
print(memory.get_memory_summary())
memory.cleanup_memory()

# Explicit backend selection
file_memory = AgentMemory("file-demo", backend=FileBackend(".superoptix/memory"))
sqlite_memory = AgentMemory("sqlite-demo", backend=SQLiteBackend(".superoptix/mem.db"))

Configure Memory via DSPy Adapters (JSON)

SuperOptiX integrates memory into DSPy-based agents through adapters. You don't need to wire internals—provide a JSON-like configuration dict, and the adapter will handle the complete memory lifecycle.

Example JSON Config

{
  "llm": {
    "provider": "ollama",
    "model": "llama3.2:1b",
    "api_base": "http://localhost:11434",
    "temperature": 0.2
  },
  "persona": {
    "name": "MemoryDemo",
    "description": "Demonstrates SuperOptiX layered memory"
  },
  "memory": {
    "enabled": true,
    "enable_embeddings": true
  }
}

Advanced Memory Configuration

{
  "llm": {
    "provider": "ollama",
    "model": "llama3.2:1b",
    "api_base": "http://localhost:11434"
  },
  "persona": {
    "name": "AdvancedMemoryBot",
    "description": "Advanced memory configuration example"
  },
  "memory": {
    "enabled": true,
    "enable_embeddings": true,
    "short_term_capacity": 200,
    "memory_retrieval": {
      "max_memories": 5,
      "min_similarity": 0.3,
      "include_conversation_history": true
    },
    "episodic_tracking": {
      "auto_start_episodes": true,
      "event_logging": true,
      "outcome_tracking": true
    }
  }
}

Configure Memory in SuperSpec (YAML)

SuperSpec is SuperOptiX's declarative DSL. You describe your agent, and SuperOptiX compiles it to a runnable DSPy pipeline.

apiVersion: agent/v1
kind: AgentSpec
metadata:
  name: memory-demo
  id: memory_demo
  namespace: demo
  level: genies
spec:
  language_model:
    location: local
    provider: ollama
    model: llama3.1:8b
    api_base: http://localhost:11434
    temperature: 0.7
    max_tokens: 2048

  memory:
    enabled: true
    short_term:
      enabled: true
      max_tokens: 2000
      window_size: 10
    long_term:
      enabled: true
      storage_type: local    # file | sqlite | redis
      max_entries: 500
      persistence: true
    episodic:
      enabled: true
      max_episodes: 100
    context_manager:
      enabled: true
      max_context_length: 4000
      context_strategy: sliding_window

# Ensure a local model is installed (Ollama is the default backend)
super model install llama3.2:8b

# Compile and run the agent
super agent compile memory_demo
super agent run memory_demo --goal "Show me how memory works in SuperOptiX"

Practical Patterns and Tips

References