# Memory & Semantic Search Setup - OpenClaw Guide

OpenClaw memory and semantic search help agents remember context, find past work, and avoid repeated prompts. Learn how to configure, test, and fix common setup issues.

## What Is Memory in OpenClaw?

Memory in OpenClaw stores useful context that your agent can reuse later. It can include:

- Project rules
- User preferences
- Client requirements
- Previous decisions
- Workflow instructions
- Repeated task formats
- Important summaries

Example: if you tell OpenClaw, "For this client, always send short weekly updates," memory helps the agent remember that preference in future tasks.

Without memory, the agent may forget instructions, repeat questions, or lose important context during long workflows. Very impressive technology, until it forgets what you said five minutes ago.

## What Is Semantic Search in OpenClaw?

Semantic search helps OpenClaw find saved information by meaning, not just exact words.

For example, if you search `pricing issue`, semantic search may also find related notes about:

- Billing problem
- Invoice error
- Subscription failure
- Payment dispute

This is useful when your OpenClaw workspace has notes, documents, support history, research, or previous workflow outputs.

## Why Memory & Semantic Search Matter in OpenClaw

OpenClaw is more useful when it can work with past context.

Without memory and semantic search, OpenClaw may:

- Forget previous decisions
- Repeat the same questions
- Lose context in long conversations
- Miss project-specific rules
- Return generic answers
- Break multi-step workflows

With memory and semantic search, OpenClaw can:

- Recall saved instructions
- Search previous notes
- Reuse project knowledge
- Improve workflow consistency
- Reduce repeated prompting
- Handle longer-running tasks more reliably

For real workflows, memory is not a luxury. It is the difference between an agent and a goldfish with API access.

## Common Memory & Semantic Search Problems

You may need to fix your OpenClaw memory setup if you see issues like:

- OpenClaw forgets previous messages
- Memory files are not saving
- Semantic search returns weak results
- Context overflow errors appear
- Embedding provider hits rate limits
- Memory disappears after gateway restart
- Voice messages fail when memory is enabled
- Search results are outdated or irrelevant
- Agent says old messages were compacted or forgotten

These problems usually come from configuration, storage, gateway, embedding, or context settings.

## Common Error Messages

You may see errors like:

- Context overflow: prompt too large for the model
- No API key found for provider
- Memory file not found
- Semantic search failed
- Embedding provider rate limit reached
- Messages were compacted

You may also see silent problems, such as an empty memory folder, ignored old context, or search results that look completely unrelated. Because naturally, the worst bugs do not even introduce themselves.

## Before You Configure Memory

Before changing memory settings, check that your basic OpenClaw setup works. You need:

- OpenClaw installed or hosted
- Gateway running
- Working AI model configured
- Memory feature enabled
- Storage path available
- Enough disk space
- Correct file permissions
- Embedding provider selected for semantic search

Run these checks first:

```bash
openclaw gateway status
openclaw --version
openclaw configure --get features.memory
ls -la ~/.openclaw/memory/
df -h ~/.openclaw/
```

### What These Commands Check

- `openclaw gateway status` - checks if the gateway is running
- `openclaw --version` - shows installed OpenClaw version
- `openclaw configure --get features.memory` - checks if memory is enabled
- `ls -la ~/.openclaw/memory/` - checks memory files and permissions
- `df -h ~/.openclaw/` - checks available disk space

If the gateway is down, fix that first. Memory cannot work properly when the service responsible for writing and reading context is not running. Shocking, yes.

## How to Enable Memory in OpenClaw

Start with basic memory before enabling semantic search.

**Step 1: Open memory configuration**

```bash
openclaw configure --section memory
```

**Step 2: Enable memory**

Set memory to enabled in your OpenClaw configuration:

```json
{
  "features": {
    "memory": true
  }
}
```

**Step 3: Restart the gateway**

```bash
openclaw gateway restart
```

**Step 4: Test memory**

Send this test prompt:

> Remember that this OpenClaw workspace is used for customer support automation.

Then ask:

> What is this OpenClaw workspace used for?

If OpenClaw recalls the saved context, basic memory is working.

## How to Configure Semantic Search in OpenClaw

Semantic search needs embeddings. Embeddings convert text into searchable meaning so OpenClaw can find related content later.

To configure semantic search, set:

- Embedding provider
- Embedding model
- API key or local endpoint
- Search result limit
- Minimum relevance score
- Chunk size
- Metadata fields
- Index location or vector database

Example configuration:

```json
{
  "memorySearch": {
    "enabled": true,
    "provider": "local",
    "query": {
      "maxResults": 5,
      "minScore": 0.75
    }
  }
}
```

After changing semantic search settings, restart the gateway:

```bash
openclaw gateway restart
```

Then test semantic search with a prompt like:

> Search previous notes for anything related to customer refund policy.

Good results should be relevant, specific, and tied to saved context.

## Fix Context Overflow in OpenClaw

A common memory error is:

> Context overflow: prompt too large for the model

This happens when OpenClaw sends too much context to the model.

**Fix it**

- Start a new session: `/new`
- Reset the current session: `/reset`
- Reduce semantic search results:

```json
{
  "memorySearch": {
    "query": {
      "maxResults": 3,
      "minScore": 0.8
    }
  }
}
```

Also check these settings:

- `contextTokens`
- `maxResults`
- `minScore`
- `contextPruning`
- `ttl`
- `keepLastAssistants`
- `compaction`

Best practice: do not inject every old memory into every prompt. That is not intelligence. That is hoarding with JSON.

## Fix Memory Files Not Saving

If memory is enabled but files are not saving, check the gateway, folder, permissions, and disk space.

```bash
openclaw gateway status
ls -la ~/.openclaw/memory/
df -h
```

If permissions are wrong, fix them:

```bash
chmod -R u+rw ~/.openclaw/memory/
```

Then restart the gateway:

```bash
openclaw gateway restart
```

### Common Causes

- **Empty memory folder** - Gateway not running. Restart the gateway.
- **Permission denied** - Folder not writable. Fix permissions.
- **No new files** - Memory disabled. Enable memory.
- **Save fails** - Disk full. Free disk space.
- **Wrong path** - Bad config. Check memory path.

For Windows users, also check folder path format and file permissions.

## Fix Semantic Search Rate Limits

Semantic search may fail if your embedding provider hits rate limits.

Common error:

> Embedding provider rate limit reached

**Fix it**

Reduce search result count:

```json
{
  "memorySearch": {
    "query": {
      "maxResults": 3
    }
  }
}
```

Or disable semantic search temporarily:

```json
{
  "memorySearch": {
    "enabled": false
  }
}
```

Then restart:

```bash
openclaw gateway restart
```

Other fixes:

- Use fewer chunks
- Reduce indexing frequency
- Add retry/backoff settings
- Switch embedding provider
- Use local embeddings for testing
- Use a paid provider for production

If semantic search is central to your workflow, do not build it on a provider limit that collapses the moment your agent does real work. Bold strategy, terrible outcome.

## Fix Weak or Irrelevant Search Results

If semantic search returns poor results, the problem is usually not OpenClaw itself. It is usually bad indexing.

### Causes

- Chunks are too large
- Chunks are too small
- No metadata
- Old index is not updated
- Wrong embedding model
- Search result limit is too high
- Minimum relevance score is too low

### Fixes

- Re-index documents
- Add metadata
- Improve chunk size
- Increase `minScore`
- Remove outdated memory
- Separate projects or workspaces
- Test with real user queries

Example stricter query setting:

```json
{
  "memorySearch": {
    "query": {
      "maxResults": 5,
      "minScore": 0.78
    }
  }
}
```

## Fix Context Loss After Gateway Restart

If OpenClaw loses memory after a restart, check whether memory files exist and whether the gateway is crashing.

```bash
openclaw gateway logs --lines 200
journalctl -u openclaw --since "24 hours ago" | tail -50
dmesg | grep -i "killed process"
ls -la ~/.openclaw/memory/
```

### Common Causes

- **Gateway crashed** - Check logs and restart.
- **VPS ran out of RAM** - Add swap or upgrade server.
- **Memory path changed** - Correct config path.
- **Files not persisted** - Use persistent storage.
- **Service user lacks permission** - Fix ownership/permissions.

If you run OpenClaw on a small VPS, memory and semantic search can fail when the server runs out of RAM. Upgrade the VPS or use managed hosting if you need reliable always-on workflows.

## Fix Voice Message Issues When Memory Is Enabled

In some setups, voice messages may fail when experimental session memory is enabled.

**Symptoms**

- Voice message is ignored
- Transcription works but no reply appears
- Text input works but voice input fails
- Bot stops responding after voice input

**Fix it**

Disable experimental session memory:

```json
{
  "memorySearch": {
    "experimental": {
      "sessionMemory": false
    }
  }
}
```

Restart the gateway:

```bash
openclaw gateway restart
```

Then test text input first. After text works, test voice input again. Also check your transcription provider settings if voice still fails.

## Recommended OpenClaw Memory Configuration

Use this as a safe starting point and adjust based on your setup:

```json
{
  "features": {
    "memory": true
  },
  "memorySearch": {
    "enabled": true,
    "provider": "local",
    "query": {
      "maxResults": 5,
      "minScore": 0.75
    },
    "experimental": {
      "sessionMemory": false
    }
  },
  "context": {
    "pruning": "cache-ttl",
    "ttl": "24h",
    "compaction": "archive"
  }
}
```

After applying changes:

```bash
openclaw gateway restart
```

This setup keeps memory enabled, limits retrieval size, avoids overly aggressive context injection, and disables experimental session memory if it causes issues.

## Test Your Memory and Semantic Search Setup

After configuration, test in three parts.

**1. Memory test**

> Remember that this OpenClaw workspace is used for customer support automation.

Then ask:

> What is this OpenClaw workspace used for?

**2. Semantic search test**

> Search previous notes for anything related to refund policy.

**3. Context test**

> Use the saved project rules and summarize the next action.

A good setup should return answers that are relevant, short, source-aware, consistent, and based on saved context. If the result is vague or unrelated, fix chunking, metadata, provider settings, or index quality.

## When to Use Managed OpenClaw Hosting

Use managed OpenClaw hosting when you want to run OpenClaw reliably without spending time on server setup, gateway issues, storage paths, or uptime problems.

Managed hosting makes sense if:

- You want OpenClaw running 24/7 for real workflows
- You do not want to manage VPS setup, ports, or background services
- Your memory and semantic search setup needs stable storage
- You want fewer gateway crashes and manual restarts
- You are connecting tools like Telegram, WhatsApp, Discord, Slack, or webhooks
- You need workflows to keep running even when your local machine is off
- You want to avoid debugging embedding, memory, and file permission issues
- You are moving from testing OpenClaw to using it for actual work

For local experiments, manual setup is fine. For always-on agents, connected tools, memory, and semantic search, managed hosting is usually the cleaner path.

With Ampere.sh, you can run OpenClaw without handling server maintenance, uptime monitoring, ports, storage setup, or backend configuration yourself.

## Frequently Asked Questions

### Why is OpenClaw memory not saving?

OpenClaw memory may not save if the gateway is stopped, memory is disabled, the storage path is wrong, permissions are missing, or the disk is full.

### How do I fix context overflow in OpenClaw?

Start a new session, reset the current session, reduce semantic search results, increase the minimum relevance score, and avoid injecting too much old memory into each prompt.

### Why is semantic search returning irrelevant results?

Semantic search usually returns weak results because of poor chunking, missing metadata, outdated indexes, weak embeddings, or low relevance score settings.

### Do I need embeddings for semantic search?

Yes. Semantic search requires embeddings because embeddings convert text into searchable meaning.

### Should I use local or hosted embeddings?

Use local embeddings for testing and privacy. Use hosted embeddings for more reliable production workflows. For less setup work, use managed OpenClaw hosting.

### Is managed hosting better for OpenClaw memory setup?

Managed hosting is better if you want persistent workflows, connected tools, uptime, memory, semantic search, and fewer configuration problems without managing a VPS yourself.