Context Items

Overview

Context items are reusable text snippets that can be attached to chats as system prompts. They support semantic search powered by pgvector embeddings, allowing users to find relevant context by meaning rather than keywords.

How context works

When a chat is created with a context_text value, the backend inserts it as a system message at position 0:

POST /api/sessions/{session_id}/chats
{
  "model_name": "GPT-4",
  "title": "Medical Q&A",
  "context_text": "You are a medical assistant specializing in cardiology."
}

This results in the following message history:

Position	Role	Content
0	system	You are a medical assistant specializing in cardiology.
1	user	What causes atrial fibrillation?
2	assistant	Atrial fibrillation is caused by…

Every subsequent LLM call includes the system message, giving the model persistent instructions.

Context item management

Creating a context item

POST /api/context-items
{
  "title": "Cardiology Expert",
  "category": "medical",
  "tags": ["cardiology", "expert"],
  "content": "You are a cardiologist with 20 years of experience..."
}

When created, the backend calls Ollama’s embedding API to generate a 768-dimensional vector:

POST http://ollama:11434/api/embeddings
{ "model": "nomic-embed-text", "prompt": "You are a cardiologist..." }

The embedding is stored in the context_items.embedding column. If Ollama is unavailable, the item is created without an embedding (semantic search will skip it).

Listing context items

GET /api/context-items?offset=0&limit=50

Returns items owned by the current user plus shared items (where owner = 'all').

Searching context items

GET /api/context-items/search?q=heart+disease&limit=10

This endpoint:

Generates an embedding for the query text using Ollama
Performs a cosine similarity search using pgvector
Returns results ranked by similarity score

SELECT *, 1 - (embedding <=> $1::vector) AS similarity
FROM context_items
WHERE (owner = 'all' OR owner = $2) AND embedding IS NOT NULL
ORDER BY embedding <=> $1::vector
LIMIT $3

Embedding model

Embeddings are generated using Ollama’s nomic-embed-text model, which produces 768-dimensional vectors. This model must be pulled before using the context features:

ollama pull nomic-embed-text

The embedding service is implemented in backend/src/services/embedding.rs and calls the Ollama API at {OLLAMA_HOST}/api/embeddings.

Query suggestions

A separate table query_items stores pre-populated query suggestions with embeddings. The suggestions endpoint finds semantically similar queries:

GET /api/suggestions?q=explain+transformers&limit=5

Response:

[
  { "id": "...", "query": "How do transformer models work?", "similarity": 0.92 },
  { "id": "...", "query": "Explain attention mechanisms", "similarity": 0.87 }
]

Ownership model

Context items have an owner field:

'all' — Shared with all users (read-only for non-owners)
User UUID string — Private to that user

RLS policies enforce this at the database level:

Anyone can SELECT items where owner = 'all' or owner matches their user ID
Users can only INSERT, UPDATE, and DELETE items they own

Frontend: ContextPicker

The ContextPicker.svelte component provides a search interface for context items when creating a new chat. It calls the search endpoint as the user types and displays results ranked by similarity. Selecting an item populates the context_text field in the Add Chat dialog.

pgvector indexing

The context_items table uses an IVFFlat index for fast approximate nearest neighbor search:

CREATE INDEX idx_context_items_embedding ON public.context_items
    USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);