Agent Memory System

GeniSpace agents use a layered memory system that automatically stores and retrieves relevant information across conversations, giving users a more coherent and personalized experience. This guide covers the memory architecture, how to configure it, and best practices.

Three-Layer Memory Architecture

When memory is enabled, the system is always organized into three layers. They are not mutually exclusive isolation modes you pick between — every layer is active at once, and the system automatically decides where new memories are stored and how stored memories are ranked during retrieval.

Session Memory

• Content: Conversation context, task state, and decision points for the current chat session
• Scope: The active session
• Default importance threshold: ~0.3 (lower-importance, short-lived context is kept here)

User Memory

• Content: Personal information, preferences, and individual context
• Scope: Shared across all sessions for the same user
• Default importance threshold: ~0.5

Agent (General) Memory

• Content: Professional knowledge, best practices, and common Q&A
• Scope: Shared across users and sessions for the same agent (within the current space)
• Default importance threshold: ~0.7 (only high-importance, broadly useful knowledge is promoted here)

In addition to these three vector-stored layers, the agent maintains short-term conversation state during a run. That short-term state is handled automatically and is not separately configured.

How Memory Works

Storage (automatic layer selection)

You do not choose a layer when memory is written. The system decides the storage layer automatically based on the content's importance score and memory type:

• Personal information and preferences are routed toward User Memory.
• High-importance professional knowledge is promoted to Agent (General) Memory.
• Conversation and task context is kept in Session Memory.
• By default, content is at least kept in Session Memory.

Each layer has an importance threshold that you configure (see below). The threshold controls how important a piece of content must be before it is stored at that layer.

Retrieval (weighted ranking)

At the start of each turn, the agent searches all three layers in parallel and merges the results. Every candidate memory is scored and the best ones are injected into the agent's context. The ranking formula is:

final_score = similarity × layer_weight × (1 + importance)

• similarity: semantic match between the user input and the stored memory (vector search)
• layer_weight: the configured weight for the layer the memory came from
• importance: the memory's stored importance score

Retrieval is also bounded per layer by configurable limits, so each layer contributes at most a set number of memories.

Configuring Memory

Open the Memory Configuration section on the agent configuration page. Configuration is split into two groups: Storage and Retrieval.

1. Enable Memory

☑️ Enable Memory

Turning this on activates the full layered architecture (Session + User + General memory, plus short-term session state). When it is off, no memory is stored or retrieved.

• Conversational agents: typically enabled to maintain context and personalization across sessions.
• Task agents: typically disabled, since task agents focus on structured input/output.

2. Storage Configuration — Importance Thresholds

Set the importance threshold for each layer. The system uses these thresholds, together with content type, to decide where a memory is stored.

Layer	Field (importance_thresholds)	Range	Default
Session	session	0–1	0.3
User	user	0–1	0.5
General (Agent)	agent	0–1	0.7

• Session threshold: storage threshold for conversation context.
• User threshold: storage threshold for personal information.
• General threshold: storage threshold for professional knowledge.

3. Retrieval Configuration

Retrieval has two per-layer settings: limits and weights.

Retrieval limits per layer (layer_limits) — the maximum number of memories pulled from each layer:

Layer	Field	Range	Default
Session	session	0–20	4
User	user	0–20	3
General (Agent)	agent	0–20	3

Layer weights (layer_weights) — the weight applied to each layer when ranking results (higher = more influence):

Layer	Field	Range	Default
Session	session	0–1	0.4
User	user	0–1	0.3
General (Agent)	agent	0–1	0.2

tip

The defaults favor recent conversation context (Session) while still surfacing relevant personal information (User) and shared knowledge (General). Raise a layer's limit and weight to make that layer more influential.

memoryConfig shape

The configuration is stored on the agent as a memoryConfig object:

{
  "memoryConfig": {
    "enabled": true,
    "retrieval": {
      "layer_limits": {
        "session": 4,
        "user": 3,
        "agent": 3
      },
      "layer_weights": {
        "session": 0.4,
        "user": 0.3,
        "agent": 0.2
      }
    },
    "storage": {
      "importance_thresholds": {
        "session": 0.3,
        "user": 0.5,
        "agent": 0.7
      }
    }
  }
}

Best Practices

Tuning for different use cases

• Privacy-sensitive conversations (e.g. customer consultations): keep weight and limit on Session higher and reduce General memory influence, so responses rely on the current conversation rather than shared knowledge.
• Personal assistants: give User memory more weight and a higher limit so preferences and history carry across sessions.
• Shared knowledge assistants used by many space members: raise the General layer's limit and weight, and lower its importance threshold so more professional knowledge is promoted and retrieved.

Performance tips

1. Keep per-layer limits modest: retrieving too many memories can slow responses and dilute relevance.
2. Tune importance thresholds: a higher General threshold keeps only the most valuable knowledge in the shared layer.
3. Clean up stale memories: remove outdated or incorrect entries through the memory management UI or API.

Memory Management API

Agent memory can be managed through the agent memory endpoints (/agents/{agentId}/memory/*). These let you list, create, search, migrate, and clear memories.

List memories

const res = await fetch(
  `/agents/${agentId}/memory?page=1&limit=20&isolation_level=all`,
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
// isolation_level: all | session | user | agent
// optional filters: memory_type, session_id, search

Create a memory (manual)

When creating a memory manually you must specify target_layers, and only agent or user are allowed — the Session layer cannot be written manually (it is populated automatically from conversations).

await fetch(`/agents/${agentId}/memory`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'The customer prefers a dark theme and concise UI.',
    memory_type: 'preference',
    importance_score: 0.6,
    tags: ['ui', 'preference'],
    target_layers: ['user'] // agent or user only
  })
});

Search memories

const res = await fetch(`/agents/${agentId}/memory/search`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'the user’s interface preferences',
    isolation_levels: ['session', 'user', 'agent'],
    limit: 5,
    importance_threshold: 0.3
  })
});

Migrate a memory between layers

await fetch(`/agents/${agentId}/memory/migrate`, {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    memory_id: 'mem_123',
    source_layer: 'session',
    target_layer: 'user'
  })
});

Clear a layer

// Clear all memories in one layer (isolation_level: session, user, or agent)
await fetch(`/agents/${agentId}/memory/clear`, {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ isolation_level: 'session' })
});

Memory statistics

const res = await fetch(`/agents/${agentId}/memory/stats`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' }
});
const { data } = await res.json();
// data.stats.layer_breakdown -> { agent, user, session }

Statistics are reported per layer via layer_breakdown.{agent, user, session}.

FAQ

Details

How does the agent decide which layer a memory goes into?

Storage is automatic. The system looks at the content's importance score and memory type: personal information and preferences lean toward User memory, high-importance professional knowledge is promoted to General (Agent) memory, and conversation/task context stays in Session memory. By default, content is at least kept in Session memory.

Details

Can I write directly to the Session layer through the API?

No. Manual creation only allows the agent or user layers. The Session layer is populated automatically from the conversation.

Details

How is the order of retrieved memories determined?

Each candidate memory is scored as similarity × layer_weight × (1 + importance), then the top results (bounded by each layer's limit) are injected into the agent's context. Adjust the layer weights and limits to change which layer has more influence.

Details

How does the memory system handle multimodal content?

Memories are retrieved using vector (semantic) similarity, which works across languages and supports matching against content derived from text and images.

Details

How can I optimize memory performance?

Keep per-layer retrieval limits modest, tune the importance thresholds so only valuable content is promoted to higher layers, and periodically remove stale or incorrect memories.

Next Steps

Explore more agent features:

• Learn about the complete feature set in Agent Overview
• Configure tools in the MCP Tool Invocation System
• Master the Tool System for operators and data sources
• Explore API Integration to integrate agents into your applications

Related guides:

• Workflow Engine: Learn how agents work with workflows
• Data & Knowledge Base: Provide professional knowledge support for agents