---
description: Configuration reference for the memory layer including embedding provider, staleness watcher, and persona tool access.
---

# Memory Configuration

## Config Reference

```yaml
memory:
  enabled: true
  embedding:
    provider: ollama          # "ollama" or "noop"
    ollama:
      url: "http://localhost:11434"
      model: "nomic-embed-text"
      timeout: 30s
  staleness:
    enabled: true
    interval: 15m             # How often to check for stale memories
    batch_size: 50            # Records per staleness check cycle
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | bool | `true` (when database available) | Enable the memory layer. Set `false` to explicitly disable. |
| `embedding.provider` | string | `noop` | Embedding provider: `ollama` for real embeddings. Anything else (including unset) selects the noop placeholder; memory writes persist with `Embedding: nil` and the apigateway embed-job queue refuses to start. Semantic features stay off until a real provider is wired. |
| `embedding.ollama.url` | string | `http://localhost:11434` | Ollama API base URL |
| `embedding.ollama.model` | string | `nomic-embed-text` | Ollama model name (768-dim) |
| `embedding.ollama.timeout` | duration | `30s` | HTTP timeout for embedding API calls |
| `staleness.enabled` | bool | `false` | Enable background staleness watcher |
| `staleness.interval` | duration | `15m` | Interval between staleness check cycles |
| `staleness.batch_size` | int | `50` | Number of records to check per cycle |

!!! note
    Memory requires `database.dsn` to be configured. Without a database, memory tools will not be registered.

## Persona Configuration

Memory tools (`memory_manage`, `memory_recall`) are opt-in. Add `memory_*` to a persona's `tools.allow` list:

```yaml
personas:
  definitions:
    analyst:
      tools:
        allow: ["trino_*", "datahub_*", "memory_*"]
    admin:
      tools:
        allow: ["*"]
```

## Embedding Provider

The memory layer generates 768-dimensional embeddings for semantic search using [Ollama](https://ollama.ai/) with the `nomic-embed-text` model.

When Ollama is unavailable, memory records are stored without embeddings and a warning is logged. Semantic recall (`memory_recall` with `semantic` or `auto` strategy) requires embeddings to function. Entity and graph recall strategies work without embeddings.

### Unconfigured State

When `memory.embedding.provider` is unset or unrecognized, the platform substitutes a noop placeholder that returns zero vectors. This is the documented degraded state, not an error: the platform still boots so Trino, S3, DataHub, audit, OAuth, and every other non-embedding feature remains available.

In this state:

- Startup logs one `WARN` line naming `memory.embedding.provider` as the key to set.
- `GET /api/v1/admin/embedding/status` returns `{ "kind": "noop", "status": "unconfigured", ... }`.
- The portal renders an amber banner on the API Catalogs and Memory pages.
- Memory writes persist `Embedding: nil` (symmetric with the recall-side guard that refuses to vector-search zero vectors).
- The apigateway embed-job queue does not start, so spec saves do not produce zero-vector rows in `api_catalog_operation_embeddings`. Per-spec badges render "not indexed" honestly; `api_list_endpoints` falls back to lexical scoring.

To set up Ollama:

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull the embedding model
ollama pull nomic-embed-text
```

## Migration

Migration `000031_memory_records` creates the `memory_records` table with pgvector support. It automatically migrates existing data from the legacy `knowledge_insights` table and drops it.

The migration requires the pgvector PostgreSQL extension. For managed PostgreSQL services this is typically pre-installed. For self-hosted PostgreSQL:

```bash
# Ubuntu/Debian
sudo apt install postgresql-16-pgvector

# Or build from source
cd /tmp && git clone https://github.com/pgvector/pgvector.git
cd pgvector && make && sudo make install
```
