OpenClaw Long-Term Memory: Never Lose Context Again [Setup]

Every agent you build starts fresh. It knows what it was told in the system prompt and what it learned in the current session — and nothing more. For personal automation, that's often enough. For agents that need to accumulate knowledge over weeks and months, it isn't.

Long-term memory changes the equation. Instead of loading everything into context, agents store knowledge in an external database and retrieve only what's relevant to the current task. The store grows indefinitely. The context stays manageable.

Why Long-Term Memory vs Memory.md

Memory.md and long-term memory solve different problems. Understanding the distinction prevents you from misusing either.

Use both together. Keep memory.md for the small set of facts that every session needs (user name, active projects, key preferences). Put everything else in the long-term store and query it when the agent needs it.

Backend Options

OpenClaw supports three long-term memory backends as of early 2025. Each has a different setup complexity and performance profile:

• SQLite — Local file database. Zero setup. No external service required. Works on any machine. Limited by single-writer concurrency — fine for personal agents, not suitable for high-throughput multi-agent deployments.
• PostgreSQL + pgvector — Full relational database with vector search extension. Best for production, shared-access, and multi-agent configurations. Requires a Postgres instance.
• Chroma — Open-source vector database designed for AI workloads. Pure semantic search focus. Simpler than Postgres for vector-only use cases. Runs locally or as a hosted service.

SQLite Setup (Personal Agents)

SQLite is the right starting point. No installation, no external service, no credentials to manage. OpenClaw creates the database file automatically on first run.

memory:
  long_term:
    enabled: true
    backend: sqlite
    path: "~/.openclaw/memory/agent-store.db"
    embedding_model: "text-embedding-3-small"   # OpenAI embedding
    max_results: 5          # retrieve top 5 relevant memories
    relevance_threshold: 0.72   # minimum similarity score

The relevance_threshold setting is important. Set it too low and your agent retrieves marginally related memories that add noise. Too high and it misses relevant context. Start at 0.72 and adjust based on retrieval quality in your specific domain.

PostgreSQL + pgvector (Production)

For production deployments, shared agent stores, or high write-frequency scenarios, PostgreSQL with the pgvector extension is the right choice. pgvector adds native vector similarity search to Postgres without a separate service.

# Install pgvector on Ubuntu
sudo apt install postgresql-16-pgvector

# In psql: enable extension
CREATE EXTENSION vector;

# OpenClaw config
memory:
  long_term:
    enabled: true
    backend: postgres
    connection_string: "postgresql://user:pass@localhost:5432/openclaw_memory"
    embedding_model: "text-embedding-3-small"
    vector_dimensions: 1536    # match your embedding model dimensions
    max_results: 8
    relevance_threshold: 0.70
    ttl_days: 90               # expire memories after 90 days

Semantic Retrieval Configuration

Retrieval quality depends on how you configure the query process. OpenClaw runs retrieval automatically when the agent encounters a task — but you can tune what triggers retrieval and how many results come back.

memory:
  long_term:
    retrieval:
      auto_query: true          # agent auto-retrieves on each turn
      query_on_keywords:        # also trigger on specific words
        - "remember"
        - "previously"
        - "last time"
        - "as we discussed"
      max_context_injection: 2000   # max tokens from retrieved memories
      format: bullet_points         # inject as bullets, not raw text

The max_context_injection limit is critical. Without it, a query that matches many high-relevance memories could inject thousands of tokens — defeating the purpose of keeping memories out of the main context. Cap it and let the relevance threshold do the filtering.

Shared Memory Across Multiple Agents

The long-term store's multi-agent capability is where the real power appears. Research agents write findings. Execution agents read them. Customer-facing agents store interaction notes. Analyst agents retrieve patterns.

agents:
  - name: researcher
    memory:
      long_term:
        store: shared-team-store
        namespace: research        # writes tagged as 'research'
        write_on: task_completion

  - name: executor
    memory:
      long_term:
        store: shared-team-store
        namespace: all             # reads from all namespaces
        read_only: false

Namespace your entries when agents have different roles. An executor shouldn't retrieve raw research notes when looking for execution history. Namespacing keeps retrieval targeted without requiring separate database instances.

Common Mistakes

Not setting a TTL on time-sensitive memories is the most common mistake. An agent that stores "the user's current project is X" will retrieve that memory 6 months later when the project has changed. Mark time-sensitive facts with short TTLs and re-verify before acting on retrieved information that's more than a few weeks old.

Storing raw tool outputs in long-term memory bloats the store with low-signal data. A web search result from three months ago has little value today. Store processed insights — what the agent concluded from data — not the raw data itself. The store should grow in wisdom, not in raw bytes.

Skipping the relevance threshold lets low-quality matches pollute your agent's context. A retrieved memory with 0.51 similarity to the query is probably noise. Set a threshold and keep it there. If the agent misses relevant memories, lower the threshold incrementally — don't remove it.

Frequently Asked Questions

What is long-term memory in OpenClaw?

Long-term memory is OpenClaw's third memory layer — a persistent, queryable external store that survives indefinitely across sessions. Unlike session memory (cleared on session end) or memory.md (limited by file size), the long-term store holds structured knowledge that agents retrieve on demand using semantic search rather than loading everything into context at once.

What database backends does OpenClaw support for long-term memory?

OpenClaw supports SQLite (local, zero setup), PostgreSQL with pgvector extension (self-hosted or cloud), and Chroma (open-source vector database). SQLite is the default for personal use. PostgreSQL with pgvector is recommended for production deployments requiring shared access across multiple agents. Chroma works well for pure semantic search use cases.

How does semantic search work in OpenClaw long-term memory?

When an agent needs to retrieve from long-term memory, OpenClaw embeds the query using a configured embedding model, then performs a vector similarity search against stored memories. The most semantically relevant entries are returned — not just keyword matches. This means an agent querying 'user's preferred communication style' can find relevant context even if that exact phrase was never stored.

Can multiple agents share the same long-term memory store?

Yes. Configure multiple agents to use the same PostgreSQL or Chroma store endpoint. Shared memory enables agent specialization — one agent handles research and writes findings, another handles execution and reads those findings without re-discovering them. Namespace entries by agent if you need isolation within a shared store.

How do I prevent long-term memory from becoming stale or inaccurate?

Configure a TTL (time-to-live) for time-sensitive memories and a relevance threshold that prevents low-confidence entries from being retrieved. Run periodic pruning to remove entries older than your TTL. For factual information that may change, include a timestamp and re-verify before acting on retrieved memories that are more than a few weeks old.

What's the difference between memory.md and long-term memory store?

memory.md is loaded into context at every session start — it's always available but limited by the context window size. The long-term store is queried on demand — it can hold unlimited information but only retrieves the most relevant subset per query. Use memory.md for small, always-needed facts (user name, preferences, active projects). Use long-term store for large knowledge bases, historical session data, and shared information across agents.