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

# Architecture

> The Graph-Vector Hybrid Engine

Persona is built on a hybrid architecture that treats the graph database as both a vector store and a structured knowledge graph. This dual nature allows it to perform complex reasoning that neither pure vector search nor traditional graph queries can achieve alone.

```mermaid theme={null}
flowchart TB
    %% Styling
    classDef client fill:#f9fafb,stroke:#d1d5db,stroke-width:1px,color:#1f2937
    classDef ingestion fill:#dbeafe,stroke:#3b82f6,stroke-width:1px,color:#1e40af
    classDef retrieval fill:#f3e8ff,stroke:#9333ea,stroke-width:1px,color:#6b21a8
    classDef storage fill:#fef3c7,stroke:#d97706,stroke-width:1px,color:#92400e
    classDef db fill:#ffffff,stroke:#000000,stroke-width:2px,color:#000000,shape:cylinder

    subgraph Client ["Client Application"]
        direction TB
        Input[Raw Content]
        Query[User Query]
    end

    subgraph Ingestion ["Ingestion Pipeline"]
        direction TB
        Adapter[PersonaAdapter]
        Service[IngestionService]
        Extract[LLM Extraction]
        Embed[Embedding Client]
        Linker[Memory Linker]
        
        Input --> Adapter
        Adapter --> Service
        Service --> Extract
        Extract -->|JSON| Service
        Service --> Embed
        Embed --> Linker
    end

    subgraph Retrieval ["Retrieval Pipeline"]
        direction TB
        Retriever[Retriever]
        VectorSearch[Vector Search]
        GraphCrawl[Graph Traversal]
        Static[Static Context]
        Formatter[ContextFormatter]
        
        Query --> Retriever
        Retriever --> VectorSearch
        Retriever --> Static
        VectorSearch -->|Seeds| GraphCrawl
        GraphCrawl -->|Expanded| Formatter
    end

    subgraph Data ["Data Layer"]
        direction TB
        Store[MemoryStore]
        Neo4j[(Neo4j Graph + Vector)]
    end

    %% Cross-graph connections
    Linker -->|Persist| Store
    Store -->|Cypher| Neo4j
    VectorSearch -.->|Read| Neo4j
    GraphCrawl -.->|Read| Neo4j
    Static -.->|Read| Store
    Formatter --> Output[Structured Context]

    %% Apply Styles
    class Input,Query,Output client
    class Adapter,Service,Extract,Embed,Linker ingestion
    class Retriever,VectorSearch,GraphCrawl,Static,Formatter retrieval
    class Store,Neo4j storage
```

## The Ingestion Pipeline

The ingestion process is the "write" side of the architecture. It transforms raw, unstructured data into a structured memory graph. The entry point is the **PersonaAdapter**, a unified interface that handles data from any source—whether it's a chat log, a note, or an email.

When content enters the pipeline, it passes through the **IngestionService**, which uses a Large Language Model to perform extraction. The LLM analyzes the text to identify three distinct types of memory:

* **Episodes**: The narrative record of what happened.
* **Psyche**: Traits, preferences, and values that define the user's identity.
* **Goals**: Actionable tasks or long-term objectives.

Once extracted, these memories are embedded into vector space. The **MemoryStore** then persists them to the graph, crucially handling the linking process. It automatically creates **temporal links** (`PREVIOUS`/`NEXT`) to chain episodes together in time, and **semantic links** (`derived_from`) to connect psyche traits and goals back to the episodes where they originated.

## The Retrieval Pipeline

The retrieval process is the "read" side, designed to reconstruct context for an agent depending on the user's query. The entry point is the **Retriever**, which executes a multi-stage hybrid algorithm.

**Stage 1: Vector Search**
The system embeds the incoming query and searches the vector index for "seed memories"—nodes that are semantically relevant to the topic at hand.

**Stage 2: Graph Crawl**
Starting from these seeds, the system traverses the graph structure. It follows relationships to find connected memories that vector search would miss. It might follow a causal link to find what led to a decision, or a temporal link to see what happened next.

**Stage 3: Static Context**
Finally, the system injects "always-on" context—specifically, active goals and core psyche traits. This ensures that even if a query doesn't explicitly mention them, the agent remains aware of the user's broader identity and objectives.

The result is passed to the **ContextFormatter**, which structures the memories into a coherent XML prompt for the consuming agent.

## The Data Layer

At the foundation lies the **Data Layer**. The **MemoryStore** acts as the abstraction for all CRUD operations, ensuring that the application logic remains decoupled from the physical storage.

Below this is **GraphOps**, the low-level driver that manages database connections. The physical storage engine is **Neo4j**, which serves as both the graph database (storing nodes and relationships) and the vector index (storing embeddings). This unified storage model eliminates the need to synchronize a separate vector database with a graph database, ensuring data consistency and simplifying operations.