> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector Store

> Vector Storage — PostgreSQL pgvector, User-level Embedding Configuration

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

```mermaid theme={null}
graph TD
    subgraph Callers["Callers"]
        rag["RAGService<br/>Knowledge Base Retrieval"]
        doc["DocumentService<br/>Document Ingestion"]
        mem["MemoryService<br/>Memory Storage / Retrieval"]
    end

    subgraph VectorStore["VectorStore (Singleton)"]
        factory["create_embeddings(user_id)<br/>User-level Embedding Factory"]
        instance["PGVector<br/>collection: knowledge / memory"]
    end

    subgraph PG["PostgreSQL"]
        pgvector["pgvector Extension<br/>Vector Index + Cosine Similarity"]
        metadata["Metadata Filtering<br/>user_id, knowledge_base_id, ..."]
    end

    rag --> VectorStore
    doc --> VectorStore
    mem --> VectorStore
    VectorStore --> PG
```

### Collection Design

| Collection  | Purpose                        | Filter Fields                                                |
| ----------- | ------------------------------ | ------------------------------------------------------------ |
| `knowledge` | Knowledge base document chunks | `user_id`, `knowledge_base_id`, `document_id`, `chunk_index` |
| `memory`    | User long-term memory          | `user_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:

```mermaid theme={null}
graph TD
    start["create_embeddings(user_id)"] --> user_check{"User DB config?"}
    user_check -->|"Yes"| user_config["Use user-configured<br/>API Key / Base URL / Model"]
    user_check -->|"No"| env_check{"Environment variables?"}
    env_check -->|"Yes"| env_config["Use environment variables<br/>OPENAI_API_KEY / OPENAI_BASE_URL"]
    env_check -->|"No"| system_check{"Next.js API system default?"}
    system_check -->|"Yes"| system_config["Use system default config"]
    system_check -->|"No"| fail["Return None<br/>(vector features unavailable)"]

    user_config --> embeddings["OpenAIEmbeddings Instance"]
    env_config --> embeddings
    system_config --> embeddings
```

### Priority

| Priority    | Source                | Resolution Method                                                                                           |
| ----------- | --------------------- | ----------------------------------------------------------------------------------------------------------- |
| 1 (Highest) | User database config  | `GET /api/config/embedding` (X-User-Id header), selects the config with `isDefault=true` and `enabled=true` |
| 2           | Environment variables | `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `EMBEDDING_MODEL`                                                    |
| 3           | System default        | Next.js API system embedding configuration                                                                  |

### Supported Models

Any model compatible with the OpenAI Embeddings API format can be used:

| Model                    | Description                                                  |
| ------------------------ | ------------------------------------------------------------ |
| `text-embedding-3-small` | OpenAI default, 1536 dimensions, best cost-performance ratio |
| `text-embedding-3-large` | OpenAI high-precision, 3072 dimensions                       |
| BGE series               | Available via compatible API                                 |
| Jina Embeddings          | Available via compatible API                                 |
| Self-hosted models       | Accessible via custom `base_url`                             |

***

## Core Operations

### Write

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
# 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"})
```