Memory Management System for Conversational AI Agents

PrototipeAI provides memory infrastructure for conversational and agentic AI systems, enabling agents to retain and retrieve context across conversations, sessions, users, and workflow executions. The platform includes a memory API for generation and retrieval, granular visibility into stored memories with classification, and fine-grained control over memory instructions for agents.

Memory management supports multiple scopes: per session, per user, per entity, and episodic memory with defined lifecycle boundaries. In agentic workflows, the system provides granular control over memory sharing between agents, session-level memory isolation, and precise memory composition for context generation.

Memory Generation and Retrieval API

REST API endpoints let agents create, update, retrieve, and delete memory entries programmatically. The API accepts structured memory objects with classification tags, relevance scores, and expiration policies. Retrieval supports semantic search, keyword matching, temporal filtering, and custom relevance ranking.

• POST /api/v1/memory: Create a memory entry with content, classification, scope, and metadata
• GET /api/v1/memory: Retrieve memories by scope, entity, time range, or semantic query
• PATCH /api/v1/memory/:id: Update memory content, classification, or relevance score
• DELETE /api/v1/memory/:id: Remove a memory with an audit trail
• POST /api/v1/memory/search: Semantic or hybrid search across memory storage
• Authentication via Bearer token with scope-based permissions

Granular Memory Visualization

The platform interface displays all agent memories with classification labels, scope identifiers, creation timestamps, relevance scores, and retrieval frequency. Users inspect individual memory entries, view retrieval history, and analyze which memories agents include in conversation context. Classification tags organize memories by type (user preference, conversation fact, entity attribute, temporal event).

• Memory browser with filtering by scope, classification, and date range
• Classification labels: preferência_usuário, fato_conversação, atributo_entidade, evento_temporal, estado_fluxo_trabalho
• Relevance scores showing importance for context inclusion
• Retrieval analytics: Frequency, recency, and context usage per memory
• Memory dependency graph showing relationships between entries
• Export to CSV or JSON for external analysis

Fine-Grained Memory Instruction Control

Agents receive specific instructions defining when to create memories, what information to extract, how to classify entries, and when to retrieve stored context. The platform allows customization of memory generation rules with if-then logic, pattern matching, and entity extraction. Users adjust memory instructions through the interface or programmatically, with immediate effect on agent behavior.

• Conditional memory creation rules (e.g., "Create a memory when the user states a preference")
• Information extraction patterns defining what to remember from conversations
• Classification logic automatically labeling memory entries by type
• Retrieval triggers specifying when to fetch memories (user mention, topic change)
• Memory prioritization rules determining context inclusion order
• Instruction versioning with A/B testing of memory strategies

Session-Based Memory Management

The memory system maintains session-scoped entries that persist only during the active conversation and expire when the session ends. Session memory lets agents track conversation-specific context, temporary states, and intermediate results without polluting long-term memory. Configurable expiration policies (time-based, event-based, or manual).

• Session ID assignment for conversation grouping
• Automatic memory scoping to the current session
• Session expiration after a configurable timeout (default: 30 minutes of inactivity)
• Session memory isolation across concurrent conversations
• Promotion of session memories to persistent storage (optional)
• Session summary generation at the end of the conversation

User-Scoped Persistent Memory

User-level memories persist across sessions and channels, enabling personalized agent behavior based on historical interactions. The system maintains separate memory spaces per user with privacy controls, data retention policies, and GDPR-compliant deletion. User memories include preferences, historical facts, and relationship context.

• Unique memory namespace per user ID
• Cross-session and cross-channel memory access
• User preference tracking with version history
• Relationship context (the agent knows the user's role, history, and permissions)
• Privacy controls for sensitive user data
• Bulk export and deletion for GDPR compliance

Episodic Memory with Lifecycle Management

Episodic memory structures organize memories into bounded time periods or narrative sequences with defined beginning, middle, and end. Agents track multi-step processes, project lifecycles, or recurring events with episodic boundaries. The system automatically manages episode transitions, archiving, and retrieval based on temporal or event-based triggers.

• Episode creation with start/end events or time boundaries
• Automatic episode segmentation based on conversation patterns
• Episode-scoped memory retention (memories expire with the episode)
• Cross-episode memory linking for recurring patterns
• Episode archiving with compressed storage for historical access
• Episode-aware retrieval prioritizing the current episode's context

Entity-Based Memory Organization

Memory entries can be scoped to any entity type beyond users and sessions: projects, organizations, documents, products, or custom domain objects. Entity-scoped memories let agents maintain context about business objects, aggregate knowledge from multiple users, and provide consistent information across interactions.

• Custom entity type definitions (project, organization, document, etc.)
• Entity-scoped memory namespaces with access control
• Multi-user contributions to shared entity memories
• Entity relationship tracking for connected memories
• Entity memory summarization aggregating information from multiple sources
• Entity-aware retrieval filtering by entity attributes

Granular Memory Sharing Between Agents

In multi-agent workflows, the platform provides fine-grained control over which memories each agent can access. Configuration specifies sharing policies: no sharing (private), explicit sharing (allowlist), or broadcast (all agents). Memory sharing rules operate at the individual memory entry level or the scope level.

• Per-agent memory access control lists
• Explicit memory sharing between specific workflow agents
• Broadcast memories visible to all workflow participants
• Read-only vs. read-write memory permissions
• Conditional sharing based on workflow state or agent role
• Memory handoff protocols between sequential workflow steps

Workflow Execution Memory

Workflow-level memory tracks execution state, intermediate results, agent outputs, and decision points throughout the workflow execution. Execution memory is scoped to a single workflow run and includes automatic checkpointing for failure recovery. Each workflow step has an isolated memory space while accessing shared workflow context.

• Workflow execution ID for memory scoping
• Automatic capture of agent outputs at each workflow step
• Execution state checkpointing for recovery after failures
• Per-step isolated memory preventing contamination between agents
• Shared workflow context accessible to all steps
• Execution memory archiving after workflow completion

Agent-Specific Memory Isolation

Each agent in a workflow maintains a private memory space containing its instructions, intermediate reasoning, tool call results, and internal state. Private memories are invisible to other agents unless explicitly shared. The platform provides granular logging of each agent's memory reads and writes for debugging and optimization.

• Private memory namespace per workflow agent
• Instruction memory containing the system prompt and agent configuration
• Reasoning trace memory for multi-step thought processes
• Tool result memory caching external API responses
• Internal state memory for agent-specific variables
• Memory access logs showing reads/writes per agent

Context Composition Control

The platform provides precise control over how memories are composed into agent context. Configuration defines memory retrieval order, maximum context size, relevance thresholds, and deduplication rules. Context composition strategies balance comprehensiveness against token limits and response latency.

• Retrieval ranking: Recency, relevance, manual priority, or hybrid scoring
• Context size limits with automatic truncation or summarization
• Relevance thresholds filtering low-value memories out of context
• Deduplication eliminating redundant information
• Memory formatting templates for consistent context structure
• Dynamic context allocation adapting to conversation complexity

The platform automatically classifies memories into categories, enabling targeted retrieval and context composition:

Personalized Customer Support Agents

Support agents remember customer preferences, prior issues, product ownership, and communication style across sessions. User-scoped memory enables consistent personalized service regardless of the conversation channel (web, WhatsApp, email).

Multi-Step Research Workflows

Research workflows with specialized agents (data collection, analysis, report writing) use shared workflow memory to pass findings between steps while keeping agent-specific reasoning traces. Episodic memory bounds the research project lifecycle.

Long-Term Project Assistance

Project management agents track multi-week initiatives using episodic memory with project start and completion boundaries. Entity-scoped memory keeps project-specific context accessible to all team members working with the agent.

Knowledge Base Construction

Agents accumulate entity-scoped memories from multiple users to build shared knowledge bases about products, policies, or procedures. Memory classification enables semantic organization of accumulated knowledge.

Debugging Complex Agentic Systems

Granular memory visualization and agent-specific memory isolation let developers trace information flow through multi-agent workflows, pinpointing where context is lost or contaminated between agents.

Create a memory entry:

POST https://api.prototipeai.com/v1/memory
Authorization: Bearer {api_token}
Content-Type: application/json

{
  "content": "Usuário prefere comunicação por email ao invés de telefone",
  "classification": "preferência_usuário",
  "scope": {
    "type": "user",
    "id": "user-123"
  },
  "relevance_score": 0.9,
  "metadata": {
    "source": "conversation-456",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Response:
{
  "memory_id": "mem-789",
  "status": "created",
  "expires_at": null
}

Retrieve relevant memories:

POST https://api.prototipeai.com/v1/memory/search
Authorization: Bearer {api_token}
Content-Type: application/json

{
  "query": "preferências de comunicação",
  "scope": {
    "type": "user",
    "id": "user-123"
  },
  "limit": 5,
  "min_relevance": 0.7
}

Response:
{
  "memories": [
    {
      "memory_id": "mem-789",
      "content": "Usuário prefere comunicação por email ao invés de telefone",
      "classification": "preferência_usuário",
      "relevance_score": 0.92,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Example of memory generation instructions for an agent:

Instruções de Memória:

CRIAR MEMÓRIA quando:
- Usuário declara uma preferência (classificação: preferência_usuário)
- Usuário compartilha informação factual relevante para conversações futuras (fato_conversação)
- Fluxo de trabalho atinge checkpoint ou ponto de decisão (estado_fluxo_trabalho)

EXTRAIR informação:
- Preferências do usuário: canal de comunicação, frequência de notificação, idioma
- Atributos de entidade: nomes de produtos, IDs de projeto, referências de documento
- Eventos temporais: prazos, reuniões agendadas, datas de marco

RECUPERAR MEMÓRIAS quando:
- Usuário faz pergunta de acompanhamento referenciando conversação anterior
- Fluxo de trabalho requer contexto de etapas anteriores
- Entidade mencionada na conversação (buscar memórias com escopo de entidade)

PRIORIZAR recuperação:
1. Memórias do episódio atual (se aplicável)
2. Preferências de usuário relevantes ao tópico atual
3. Fatos de conversação recentes (últimos 7 dias)
4. Atributos de entidade para entidades mencionadas

INCLUIR no contexto:
- Máximo 10 memórias mais relevantes
- Pontuação mínima de relevância: 0.7
- Deduplicar conteúdo similar
- Formatar como lista de marcadores no prompt do sistema