> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nullclaw/nullclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Configuration

> Configure memory backends and vector search for NullClaw

NullClaw's memory system stores conversation history, facts, and context. Configure the storage backend, vector search, and memory lifecycle policies.

## Memory Profiles

Memory profiles provide preset configurations for common use cases:

```json theme={null}
{
  "memory": {
    "profile": "markdown_only"
  }
}
```

<ParamField path="memory.profile" type="string" default="markdown_only">
  Memory profile preset:

  * `markdown_only` — File-based markdown memory (default, zero setup)
  * `local_keyword` — SQLite keyword-only search
  * `local_hybrid` — SQLite + vector search hybrid
  * `postgres_keyword` — PostgreSQL keyword-only
  * `postgres_hybrid` — PostgreSQL + vector hybrid
  * `minimal_none` — Stateless, no persistent memory
  * `custom` — Manual configuration (no profile defaults)
</ParamField>

## Backend Configuration

### Basic Backend Setup

```json theme={null}
{
  "memory": {
    "backend": "markdown",
    "auto_save": true,
    "citations": "auto"
  }
}
```

<ParamField path="memory.backend" type="string" default="markdown">
  Memory backend: `markdown` (file-based), `sqlite` (local database), `postgres` (PostgreSQL), `redis`, `api`, or `none`.
</ParamField>

<ParamField path="memory.auto_save" type="boolean" default="true">
  Automatically save memory entries after each interaction.
</ParamField>

<ParamField path="memory.citations" type="string" default="auto">
  Citation style: `auto` (show when relevant), `always`, or `never`.
</ParamField>

## Vector Search Configuration

Enable semantic search with vector embeddings:

```json theme={null}
{
  "memory": {
    "search": {
      "enabled": true,
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "fallback_provider": "none",
      "store": {
        "kind": "auto",
        "qdrant_url": "",
        "qdrant_api_key": "",
        "qdrant_collection": "nullclaw_memories",
        "pgvector_table": "memory_embeddings"
      }
    }
  }
}
```

<ParamField path="memory.search.enabled" type="boolean" default="true">
  Enable vector search capabilities.
</ParamField>

<ParamField path="memory.search.provider" type="string" default="none">
  Embedding provider: `openai`, `cohere`, `voyage`, `ollama`, or `none` (disables vector search).
</ParamField>

<ParamField path="memory.search.model" type="string" default="text-embedding-3-small">
  Embedding model identifier.
</ParamField>

<ParamField path="memory.search.dimensions" type="number" default="1536">
  Embedding vector dimensions (must match model output).
</ParamField>

<ParamField path="memory.search.store.kind" type="string" default="auto">
  Vector store backend: `auto` (matches memory backend), `sidecar` (local file), `qdrant`, or `pgvector`.
</ParamField>

### Hybrid Search

Combine keyword and vector search:

```json theme={null}
{
  "memory": {
    "search": {
      "query": {
        "max_results": 6,
        "min_score": 0.0,
        "merge_strategy": "rrf",
        "rrf_k": 60,
        "hybrid": {
          "enabled": true,
          "vector_weight": 0.7,
          "text_weight": 0.3,
          "candidate_multiplier": 4
        }
      }
    }
  }
}
```

<ParamField path="memory.search.query.hybrid.enabled" type="boolean" default="false">
  Enable hybrid search combining keyword and vector results.
</ParamField>

<ParamField path="memory.search.query.hybrid.vector_weight" type="number" default="0.7">
  Weight for vector search results (0.0 to 1.0).
</ParamField>

<ParamField path="memory.search.query.hybrid.text_weight" type="number" default="0.3">
  Weight for keyword search results (0.0 to 1.0).
</ParamField>

<ParamField path="memory.search.query.merge_strategy" type="string" default="rrf">
  Result merging strategy: `rrf` (Reciprocal Rank Fusion) or `score` (weighted scores).
</ParamField>

## Memory Lifecycle

Configure memory archival and retention:

```json theme={null}
{
  "memory": {
    "lifecycle": {
      "hygiene_enabled": true,
      "archive_after_days": 7,
      "purge_after_days": 30,
      "conversation_retention_days": 30,
      "snapshot_enabled": false,
      "auto_hydrate": true
    }
  }
}
```

<ParamField path="memory.lifecycle.hygiene_enabled" type="boolean" default="true">
  Enable automatic memory hygiene (archival and purging).
</ParamField>

<ParamField path="memory.lifecycle.archive_after_days" type="number" default="7">
  Archive memories older than this many days.
</ParamField>

<ParamField path="memory.lifecycle.purge_after_days" type="number" default="30">
  Permanently delete memories older than this many days.
</ParamField>

<ParamField path="memory.lifecycle.conversation_retention_days" type="number" default="30">
  Retain conversation context for this many days.
</ParamField>

<ParamField path="memory.lifecycle.auto_hydrate" type="boolean" default="true">
  Automatically load archived memories when referenced.
</ParamField>

## PostgreSQL Backend

Use PostgreSQL for distributed deployments:

```json theme={null}
{
  "memory": {
    "backend": "postgres",
    "postgres": {
      "url": "postgresql://user:pass@localhost:5432/nullclaw",
      "schema": "public",
      "table": "memories",
      "connect_timeout_secs": 30
    },
    "search": {
      "provider": "openai",
      "store": {
        "kind": "pgvector",
        "pgvector_table": "memory_embeddings"
      }
    }
  }
}
```

<ParamField path="memory.postgres.url" type="string" required>
  PostgreSQL connection URL.
</ParamField>

<ParamField path="memory.postgres.schema" type="string" default="public">
  Database schema name.
</ParamField>

<ParamField path="memory.postgres.table" type="string" default="memories">
  Table name for memory storage.
</ParamField>

## Redis Backend

Use Redis for caching and fast retrieval:

```json theme={null}
{
  "memory": {
    "backend": "redis",
    "redis": {
      "host": "127.0.0.1",
      "port": 6379,
      "password": "",
      "db_index": 0,
      "key_prefix": "nullclaw",
      "ttl_seconds": 0
    }
  }
}
```

<ParamField path="memory.redis.host" type="string" default="127.0.0.1">
  Redis server hostname.
</ParamField>

<ParamField path="memory.redis.port" type="number" default="6379">
  Redis server port.
</ParamField>

<ParamField path="memory.redis.key_prefix" type="string" default="nullclaw">
  Prefix for all Redis keys.
</ParamField>

<ParamField path="memory.redis.ttl_seconds" type="number" default="0">
  Time-to-live for entries (0 = no expiry).
</ParamField>

## Advanced Configuration

### Chunking and Sync

```json theme={null}
{
  "memory": {
    "search": {
      "chunking": {
        "max_tokens": 512,
        "overlap": 64
      },
      "sync": {
        "mode": "best_effort",
        "embed_timeout_ms": 15000,
        "vector_timeout_ms": 5000,
        "embed_max_retries": 2,
        "vector_max_retries": 2
      }
    }
  }
}
```

### Response Cache

```json theme={null}
{
  "memory": {
    "response_cache": {
      "enabled": false,
      "ttl_minutes": 60,
      "max_entries": 5000
    }
  }
}
```

<ParamField path="memory.response_cache.enabled" type="boolean" default="false">
  Cache LLM responses for identical queries.
</ParamField>

## Example: Local Hybrid Setup

Complete configuration for local SQLite with vector search:

```json theme={null}
{
  "memory": {
    "profile": "local_hybrid",
    "backend": "sqlite",
    "auto_save": true,
    "search": {
      "enabled": true,
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "store": {
        "kind": "sidecar"
      },
      "query": {
        "max_results": 6,
        "hybrid": {
          "enabled": true,
          "vector_weight": 0.7,
          "text_weight": 0.3
        }
      }
    },
    "lifecycle": {
      "hygiene_enabled": true,
      "archive_after_days": 7,
      "purge_after_days": 30
    }
  }
}
```

<Info>
  The `local_hybrid` profile automatically applies these defaults. You only need to override specific values.
</Info>