Memory Configuration¶

SynthOrg agents have persistent memory that spans conversations and tasks. The memory system stores experiences, knowledge, skills, and relationships, and retrieves relevant memories to inject into the agent's context. This guide covers how to configure memory backends, persistence levels, retrieval tuning, shared organizational memory, and consolidation.

Memory Architecture¶

The memory system has two concerns:

• Agent memory -- per-agent memories (what an agent has learned, experienced, and knows) stored in a pluggable memory backend
• Operational data -- structured records (tasks, cost records, messages, audit entries) stored in a persistence backend (SQLite)

graph TD
    Agent["Agent"]
    Retriever["Retrieval Pipeline"]
    Backend["Memory Backend<br/><small>Mem0 (Qdrant + SQLite)</small>"]
    OrgMem["Shared Org Memory<br/><small>Core policies + extended facts</small>"]
    Persistence["Persistence Backend<br/><small>SQLite</small>"]

    Agent -->|"recall"| Retriever
    Agent -->|"store"| Backend
    Retriever --> Backend
    Retriever --> OrgMem
    Agent -.->|"tasks, costs"| Persistence

Memory Types¶

Agents store five types of memory:

Memory Levels¶

The level field controls how long memories persist:

Agent Memory Configuration¶

Configure memory in the memory section of your company config:

memory:
  backend: "mem0"
  level: session
  storage:
    data_dir: "/data/memory"
    vector_store: "qdrant"
    history_store: "sqlite"
  options:
    retention_days: null          # null = keep forever
    max_memories_per_agent: 10000
    consolidation_interval: daily
    shared_knowledge_base: true
  retrieval:
    strategy: context
    relevance_weight: 0.7
    recency_weight: 0.3
    min_relevance: 0.3
    max_memories: 20
    include_shared: true
  consolidation:
    interval: daily
    max_memories_per_agent: 10000

Top-Level Memory Fields¶

Storage Configuration¶

Memory Options¶

Retrieval Pipeline¶

When an agent needs context, the retrieval pipeline queries the memory backend, ranks results, and injects the top matches into the agent's prompt.

Retrieval Fields¶

Weight Tuning¶

For the linear fusion strategy, relevance_weight + recency_weight must equal 1.0:

retrieval:
  relevance_weight: 0.7   # prioritize semantic relevance
  recency_weight: 0.3     # with some recency bias

• Higher relevance_weight -- better for knowledge-heavy tasks where the most relevant memory matters regardless of when it was stored
• Higher recency_weight -- better for conversational contexts where recent interactions are more important
• personal_boost -- adds a bonus to the agent's own memories over shared org memories (0.1 = 10% boost)

Shared Organizational Memory¶

Beyond per-agent memory, SynthOrg supports shared organizational memory -- knowledge available to all agents:

org_memory:
  backend: "hybrid_prompt_retrieval"
  core_policies:
    - "All code must pass review before merging."
    - "Customer data is never logged or stored in plain text."
    - "Budget decisions require CFO approval above 50 EUR."
  extended_store:
    backend: "sqlite"
    max_retrieved_per_query: 5

Org Memory Fields¶

How It Works¶

The hybrid prompt + retrieval backend uses two layers:

1. Core policies -- short, critical rules injected directly into every agent's system prompt. These are always available and never filtered.
2. Extended store -- a searchable database of organizational facts, procedures, and conventions. These are retrieved on demand via the retrieval pipeline (up to max_retrieved_per_query per query).

Consolidation & Archival¶

Over time, agent memories accumulate. Consolidation manages memory volume through retention rules and archival:

consolidation:
  interval: daily
  max_memories_per_agent: 10000
  retention:
    default_retention_days: null   # keep forever by default
    rules: []                      # per-category overrides
  archival:
    enabled: false
    age_threshold_days: 90
    dual_mode:
      enabled: false
      dense_threshold: 0.5
      summarization_model: "example-medium-001"
      max_summary_tokens: 200
      max_facts: 20
      anchor_length: 150

Consolidation Fields¶

Retention¶

Per-category retention rules (uniform across all agents):

Archival¶

When archival is enabled, memories older than age_threshold_days are archived using one of two modes:

The archival system classifies each memory by density score and routes to the appropriate mode:

Practical Example¶

A complete memory configuration for a research lab that prioritizes long-term knowledge retention:

memory:
  backend: "mem0"
  level: persistent
  storage:
    data_dir: "/data/memory"
    vector_store: "qdrant"
    history_store: "sqlite"
  options:
    retention_days: null
    max_memories_per_agent: 50000
    consolidation_interval: weekly
    shared_knowledge_base: true
  retrieval:
    strategy: context
    relevance_weight: 0.8        # strong relevance bias for research
    recency_weight: 0.2
    personal_boost: 0.05
    min_relevance: 0.4           # higher threshold for quality
    max_memories: 30             # more context for complex tasks
    include_shared: true
  consolidation:
    interval: weekly
    max_memories_per_agent: 50000
    archival:
      enabled: true
      age_threshold_days: 180
      dual_mode:
        enabled: true
        dense_threshold: 0.6
        summarization_model: "example-small-001"
        max_summary_tokens: 300
        max_facts: 30

org_memory:
  backend: "hybrid_prompt_retrieval"
  core_policies:
    - "All research findings must be reproducible."
    - "Cite sources for all claims."
  extended_store:
    max_retrieved_per_query: 10

See Also¶

• Company Configuration -- full configuration reference
• Design: Memory -- memory architecture in the design spec
• Library Reference: Memory -- API documentation