Semantic Memory

Sidekick's agent uses semantic memory search to recall relevant context from past interactions. This gives the agent long-term recall — instead of treating every conversation as stateless, it can surface and reason over information it has previously encountered.

How It Works

Semantic memory is powered by vector similarity search using OpenAI's Embeddings API (text-embedding-* models). When the agent needs to recall prior context, it:

1. Encodes the current query into a high-dimensional embedding vector via the OpenAI API.
2. Compares that vector against stored memory embeddings using cosine similarity.
3. Returns the most semantically relevant memories as additional context for the current task.

The implementation lives in src/lib/agent/semantic-memory.ts and reads the API key from the environment at runtime.

Configuration

Semantic memory requires the OPENAI_API_KEY environment variable to be set.

OPENAI_API_KEY=sk-...

Obtain an API key from https://platform.openai.com/api-keys.

Graceful Degradation

If OPENAI_API_KEY is absent or invalid, semantic memory search silently returns empty results rather than throwing an error. The agent continues to function normally but without long-term recall:

Condition	Behaviour
OPENAI_API_KEY set and valid	Full semantic memory search enabled
OPENAI_API_KEY missing or invalid	Memory search returns empty; agent has no long-term recall

This means the absence of the key is not a hard blocker — the platform will not crash or degrade in any visible way — but agent response quality will be reduced for tasks that benefit from historical context.

Impact on Agent Quality

Without semantic memory, the agent:

• Cannot recall preferences, facts, or instructions from previous sessions.
• Cannot reference prior conversation history beyond the current context window.
• Will not improve its responses based on patterns learned over time.

For production deployments where agent quality matters, setting OPENAI_API_KEY is strongly recommended.

Troubleshooting

Memory search always returns empty results? Verify that OPENAI_API_KEY is correctly set in your environment and that the key has access to OpenAI's Embeddings API. You can test the key directly:

curl https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "model": "text-embedding-ada-002"}'

A successful response confirms the key is valid and embeddings access is available.