Skip to main content
Aegra supports semantic similarity search through the LangGraph Store API using PostgreSQL with pgvector. This lets agents store and retrieve information based on meaning rather than exact keyword matches.

​
Use cases

  • Conversational memory — Agents recall past interactions semantically
  • RAG applications — Store and retrieve knowledge documents by similarity
  • Personalization — Remember user preferences and retrieve them contextually
  • Multi-tenant search — Namespaced semantic search per user or tenant

​
Configuration

Add the store section to your aegra.json: 
{
  "graphs": {
    "agent": "./graphs/agent/graph.py:graph"
  },
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small",
      "fields": ["$"]
    }
  }
}

​
Options

OptionTypeRequiredDescription
dimsintegerYesEmbedding vector dimensions (must match your model)
embedstringYesEmbedding model in format provider:model-id
fieldslist[str]NoJSON fields to embed (default: ["$"] for entire document)

​
Fields configuration

The fields option controls which parts of your documents get embedded:
ValueBehavior
["$"] (default)Embed the entire document as one unit
["text", "summary"]Embed only these top-level fields
["metadata.title", "content.text"]JSON path notation for nested fields
Documents missing specified fields are still stored but won’t have embeddings for those fields. You can also override which fields to embed at put time using the index parameter.

​
Supported embedding providers

The format is provider:model-id. The provider is determined by splitting on the first colon, so bedrock:amazon.titan-embed-text-v2:0 is parsed as provider bedrock with model amazon.titan-embed-text-v2:0.
ProviderModelDimensionsConfig value
OpenAItext-embedding-3-small1536openai:text-embedding-3-small
OpenAItext-embedding-3-large3072openai:text-embedding-3-large
AWS Bedrockamazon.titan-embed-text-v2:01024bedrock:amazon.titan-embed-text-v2:0
Cohereembed-english-v3.01024cohere:embed-english-v3.0
Set the appropriate API key in your .env: 
# OpenAI
OPENAI_API_KEY=sk-...

# AWS Bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

# Cohere
COHERE_API_KEY=...

​
Usage

​
Storing items

from langgraph_sdk import get_client

client = get_client(url="http://localhost:8000")

await client.store.put(
    namespace=["user", "123", "preferences"],
    key="coding_style",
    value={
        "text": "I prefer clean code with descriptive variable names and minimal comments"
    },
)

results = await client.store.search(
    namespace_prefix=["user", "123"],
    query="How does this user like to write code?",
    limit=5,
)
# Returns the coding_style preference based on semantic similarity

​
Database requirements

Semantic store requires PostgreSQL with the pgvector extension. Use the recommended Docker image: 
postgres:
  image: pgvector/pgvector:pg18
Aegra automatically creates the necessary tables and indexes during startup.

​
Verification

After starting with semantic store configured, you should see this log: 
INFO: Semantic store enabled with embeddings: openai:text-embedding-3-small

​
Backward compatibility

If no store.index configuration is provided, Aegra operates in basic key-value mode. Existing deployments continue to work without changes.

​
Troubleshooting

Make sure you’re using a PostgreSQL image with pgvector installed: pgvector/pgvector:pg18.
Verify the embed format is correct (provider:model-id) and the corresponding API key is set in your .env.
The dims value must match your embedding model’s output dimensions exactly. For example, text-embedding-3-small outputs 1536-dimensional vectors.