Skip to main content
Zeus uses PostgreSQL pgvector as its vector storage engine, wrapped via langchain-postgres’s PGVector, providing a unified vector storage service for both Knowledge Base (RAG retrieval) and Memory (long-term memory).

​
Storage Architecture

​
Collection Design

CollectionPurposeFilter Fields
knowledgeKnowledge base document chunksuser_id, knowledge_base_id, document_id, chunk_index
memoryUser long-term memoryuser_id, scope, project_id, session_id
Each collection is obtained via VectorStore.get_instance(collection_name, embeddings), and the same collection + embeddings combination shares a singleton instance.

​
Embedding Configuration

Zeus supports user-level embedding configuration, allowing different users to use different embedding models. Configuration is resolved in the following priority order:

​
Priority

PrioritySourceResolution Method
1 (Highest)User database configGET /api/config/embedding (X-User-Id header), selects the config with isDefault=true and enabled=true
2Environment variablesOPENAI_API_KEY + OPENAI_BASE_URL + EMBEDDING_MODEL
3System defaultNext.js API system embedding configuration

​
Supported Models

Any model compatible with the OpenAI Embeddings API format can be used:
ModelDescription
text-embedding-3-smallOpenAI default, 1536 dimensions, best cost-performance ratio
text-embedding-3-largeOpenAI high-precision, 3072 dimensions
BGE seriesAvailable via compatible API
Jina EmbeddingsAvailable via compatible API
Self-hosted modelsAccessible via custom base_url

​
Core Operations

​
Write

# Write during document processing
docs_to_add = [
    LCDocument(
        page_content="Chunk content...",
        metadata={
            "user_id": "user_123",
            "knowledge_base_id": "kb_456",
            "document_id": "doc_789",
            "chunk_index": 0,
            "source": "example.pdf",
            "page": 1,
            "created_at": "2025-01-01T00:00:00",
        }
    )
]
chunk_ids = vectorstore.add_documents(docs_to_add)

​
Retrieval

# Vector similarity search + metadata filtering
results = vectorstore.similarity_search_with_score(
    query="How to configure Zeus?",
    k=5,
    filter={
        "user_id": "user_123",
        "knowledge_base_id": "kb_456",
    },
)

​
Deletion

# Delete all chunks for a document
vectorstore.delete(filter={"document_id": "doc_789"})

# Delete all data for a knowledge base
vectorstore.delete(filter={"knowledge_base_id": "kb_456"})