Inside OpenClaw: How Its Memory Architecture Powers Self‑Hosted AI Agents

2.1 Vector Store Fundamentals

At the core of OpenClaw lies a vector store—a high‑dimensional index that maps embeddings (dense numeric representations) to their original text chunks. This enables semantic similarity search, allowing agents to retrieve contextually relevant memories even when exact keyword matches are absent.

• Embeddings are generated by any compatible LLM (e.g., OpenAI, Claude, or local models).
• Vectors are stored in an HNSW graph for sub‑millisecond nearest‑neighbor queries.
• Metadata (timestamps, tags, source IDs) travels alongside each vector, enabling filtered retrieval.

2.2 Short‑Term vs Long‑Term Memory

OpenClaw separates memory into two layers:

1. Short‑Term Memory (STM): An in‑memory cache that holds the most recent interactions (typically the last few turns). STM is volatile, ultra‑fast, and ideal for context windows that fit within the LLM’s token limit.
2. Long‑Term Memory (LTM): A persisted vector store that archives all embeddings beyond the STM horizon. LTM survives restarts, scales horizontally, and supports complex queries across weeks or months of conversation history.

This dual‑layer design mirrors human cognition—working memory for immediate tasks and episodic memory for long‑term knowledge.

2.3 Persistence and Durability

OpenClaw writes LTM vectors to durable storage (e.g., PostgreSQL, SQLite, or cloud object stores). The engine uses write‑ahead logs and periodic snapshots to guarantee ACID properties. In case of a crash, the system can replay logs and restore the exact state without data loss.

Persistence also enables knowledge transfer: an agent trained on one dataset can be redeployed with its entire memory intact, accelerating onboarding for new users.

2.4 Sharding Strategy for Scalability

As memory grows, a single node becomes a bottleneck. OpenClaw automatically shards the vector store across multiple workers based on a configurable hash of the document ID. Each shard maintains its own HNSW index, allowing parallel insertion and query processing.

Sharding brings two key benefits:

• Horizontal scaling: Add more nodes to increase capacity without downtime.
• Fault isolation: Failure of one shard does not affect the entire memory pool.

2.5 Retrieval Mechanisms

OpenClaw offers three retrieval modes:

1. Exact match (metadata filters).
2. Semantic similarity (k‑nearest neighbor search).
3. Hybrid (metadata + similarity scoring).

The API lets agents specify a top_k value and optional filters such as source="email" or date>="2024-01-01". The engine returns a ranked list of relevant chunks, ready to be injected into the LLM prompt.

3.1 Initializing the Vector Store

The first step is to create a VectorStore instance with your chosen backend:

from openclaw.memory import VectorStore

# Choose a persistent backend (PostgreSQL example)
store = VectorStore(
    backend="postgresql",
    connection_string="postgresql://user:pass@localhost:5432/openclaw",
    dimension=768,               # Embedding size
    metric="cosine"
)

print("Vector store initialized:", store.is_ready())

3.2 Adding Short‑Term Memory

Short‑term entries are kept in an in‑memory buffer. Use the STM helper to push recent turns:

from openclaw.memory import STM

# Create a short‑term memory buffer with a capacity of 10 turns
stm = STM(max_turns=10)

# Example: add a user message and the assistant response
stm.add_turn(user="What are the quarterly sales figures?", 
             assistant="The Q1 sales were $1.2M, Q2 $1.5M...")

# Retrieve the current context for prompt injection
context = stm.get_context()
print("Current STM context:", context)

3.3 Persisting Long‑Term Memory

When a conversation exceeds the STM window, archive it to LTM:

from openclaw.memory import LTM

# LTM wraps the same VectorStore for persistence
ltm = LTM(store)

def archive_turns(turns):
    for turn in turns:
        # Generate an embedding (using any model, e.g., OpenAI)
        embedding = embed_text(turn["text"])
        ltm.upsert(
            id=turn["id"],
            vector=embedding,
            metadata={
                "role": turn["role"],
                "timestamp": turn["timestamp"]
            }
        )

# Archive the oldest turn from STM
oldest = stm.pop_oldest()
archive_turns([oldest])

3.4 Configuring Sharding

Enable sharding by specifying a shard count and a hash key:

store.enable_sharding(
    shard_count=4,               # Number of shards
    hash_key="document_id"       # Field used for distribution
)

print("Sharding enabled with", store.shard_count, "shards")

3.5 Querying and Retrieval

Retrieve relevant memories using semantic similarity and optional filters:

query = "What were the sales trends in Q2?"
query_vec = embed_text(query)

results = ltm.search(
    vector=query_vec,
    top_k=5,
    filters={"role": "assistant"}   # Only retrieve assistant replies
)

for hit in results:
    print(f"Score: {hit.score:.3f} | Text: {hit.metadata['text']}")