Memory & Embeddings

OpenCaddis includes a persistent vector memory system that lets agents save, search, and forget information across conversations. Content is chunked, embedded, and stored as vectors in a local SQLite database.

How It Works

Content Chunker Embeddings API SQLite + sqlite-vec

Content submitted — via the MemorySave tool with optional source label and content type
Chunked — content is split into ~500 character chunks (split on paragraph boundaries \n\n, merged up to target size, max single chunk 2000 chars)
Embedded — each chunk is sent to the embeddings model to produce a 1536-dimension vector
Stored — vectors and metadata are saved to the local SQLite database

Embedding Model

Memory requires an "embeddings" model configured in fabr.json. The recommended model is text-embedding-ada-002 which produces 1536-dimension vectors.

fabr.json — Embeddings Config

{
  "Name": "embeddings",
  "Provider": "Azure",
  "Uri": "https://your-resource.openai.azure.com/",
  "Model": "text-embedding-ada-002",
  "ApiKeyAlias": "azure-key"
}

Required

The memory system will not function without an "embeddings" model configuration. If no embeddings model is configured, the Memory plugin will be disabled.

Storage

Vectors are stored locally using SQLite with the sqlite-vec extension for efficient vector similarity search.

Detail	Value
Database file	`data/opencaddis-vectors.db`
Extension	sqlite-vec
Vector dimensions	1536

Schema

Two tables work together:

embeddings table

CREATE TABLE embeddings (
    id           TEXT PRIMARY KEY,
    source       TEXT,
    content      TEXT NOT NULL,
    content_type TEXT,
    created_at   TEXT NOT NULL,
    metadata     TEXT
);

vec_embeddings virtual table

CREATE VIRTUAL TABLE vec_embeddings USING vec0(
    id        TEXT PRIMARY KEY,
    embedding float[1536]
);

Search

When an agent calls MemorySearch, the query text is embedded into a vector and compared against stored vectors using cosine similarity. Results are ranked by similarity score.

Semantic matching — finds conceptually similar content, not just keyword matches
Source filtering — optionally filter results by source label (e.g., only search memories from "research-project")
Max results — configurable via Memory:MaxResults (default 5)

Chunking Strategy

Content is split into manageable chunks for embedding:

Parameter	Value	Description
Split boundary	`\n\n`	Split on paragraph boundaries
Target chunk size	~500 chars	Merge paragraphs up to this size
Max chunk size	2000 chars	Individual chunks are capped at this length

Short content (under ~500 chars) is stored as a single chunk. Longer content is split at natural paragraph breaks and merged into chunks that stay close to the target size.

Memory Plugin Tools

The Memory plugin exposes three tools:

MemorySearch — Search by semantic similarity with optional source filter
MemorySave — Save content (auto-chunked and embedded)
MemoryForget — Delete matching memories (requires explicit "CONFIRM" parameter as a safety guard)

Memory & Embeddings