Semantic Search API Reference

Endpoints for querying agent memory entries via semantic similarity over embedding vectors.

`POST /api/memory/search`

Compute cosine similarity between a query string and stored memory entry embeddings, returning the top-K most similar results ranked by score.

Request

POST /api/memory/search HTTP/1.1
Content-Type: application/json

{
  "query": "FK constraint violations on users table",
  "top_k": 10,
  "org_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Default	Description
`query`	string	yes	—	Natural language query text. The raw JSON content of memory entries is embedded as-is (no normalization).
`top_k`	integer	no	10	Maximum number of results to return. Clamped to [1, 100] in production.
`org_id`	string (UUID)	no	—	Optional filter: returns entries only from sessions belonging to this organization. Stored as a UUID string; pass `null` or omit to skip filtering.

Response

{
  "data": [
    {
      "entry_id": "abc123...",
      "score": 0.8734,
      "content": "{\"tool\":\"query\",\"args\":\"SELECT ... FROM users WHERE id = ?\"}",
      "created_at": "2026-08-02T14:30:00Z",
      "related_cascade_targets": ["orders", "order_items"]
    },
    {
      "entry_id": "def456...",
      "score": 0.7291,
      "content": "{\"tool\":\"schema_introspect\",\"args\":\"SHOW CREATE TABLE users\"}",
      "created_at": "2026-08-02T14:31:00Z",
      "related_cascade_targets": []
    }
  ]
}

Field	Type	Description
`entry_id`	string (UUID)	Primary key of the matching memory entry.
`score`	float	Cosine similarity score in [-1, 1]. Higher values indicate greater semantic similarity to the query. Identical vectors → 1.0; orthogonal → 0.0; anti-aligned → -1.0.
`content`	string	The original memory entry content (raw JSON string stored in the `agent_memory_entries.content` column).
`created_at`	ISO-8601 datetime	When the memory entry was created.
`related_cascade_targets`	array of strings	FK cascade targets from `schema_topology`. Populated only after #021 merges; currently always empty.

Errors

Status Code	Response Body	Description
400 Bad Request	`{"error": "..."}`	Invalid request body (e.g., missing `query` field).
500 Internal Server Error	`{"error": "Embedding failed: ..."}`	Embedding model returned an error during query embedding.
500 Internal Server Error	`{"error": "Failed to query embeddings: ..."}`	Database query for stored embeddings failed.

Cosine Similarity Computation

The backend computes cosine similarity using the formula:

cosine_similarity(A, B) = (A · B) / (|A| × |B|)

Where:

A is the query embedding vector (f32)
B is a stored embedding vector (f32) retrieved from memory_entry_embeddings.embedding_vector
· denotes dot product
|·| denotes L2 norm

The computation uses ndarray for efficient matrix operations. Norms are cached in a HashMap<Vec<f32>, f32> keyed by embedding bytes to avoid repeated square root calculations across queries.

Storage Format

Stored embeddings use BLOB (binary) column type — raw f32 byte arrays serialized via bytemuck:

768 dims × 4 bytes/dim = 3072 bytes per vector (default dimension)
1536 dims × 4 bytes/dim = 6144 bytes per vector (OpenAI ada-002)

SeaORM maps Vec<u8> entity fields to BLOB columns automatically via DeriveEntityModel. The migration m20260802_000001_create_memory_entry_embeddings.rs defines the schema:

#![allow(unused)]
fn main() {
ColumnDef::new(MemoryEntryEmbeddings::EmbeddingVector)
    .binary()  // → MySQL BLOB / PostgreSQL BYTEA / SQLite BLOB
    .not_null(),
}

FK Cascade Enrichment (Deferred)

After #021 merges, the search handler will query schema_topology for CASCADE relationships on tables referenced in top-K results:

SELECT target_table FROM fk_relationships 
WHERE source_table = ? AND cascade_type = 'CASCADE'

This enriches results with metadata like "related_cascade_targets": ["orders", "order_items"], enabling queries like “find all sessions that modified tables cascading from users” to return entries mentioning FK relationships.

Example Usage (curl)

# Basic search — top 5 most similar memory entries
curl -X POST http://localhost:8000/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "agent got stuck on FK cascade detection",
    "top_k": 5
  }'

# Filter by organization
curl -X POST http://localhost:8000/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "schema introspection errors",
    "org_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

# Retrieve full result set for post-processing (top_k=100)
curl -X POST http://localhost:8000/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "tool call failures",
    "top_k": 100
  }' | jq '.data[] | {entry_id, score}'

Keyboard shortcuts

SCHEMABOUND Framework Documentation