fleet-memory/hindsight-docs/docs/developer/index.md

sidebar_position	slug
1	/

Overview

Why Hindsight?

AI assistants forget everything between sessions. Every conversation starts from zero—no context about who you are, what you've discussed, or what the agent has learned. This isn't just inconvenient; it fundamentally limits what AI agents can do.

The problem is harder than it looks:

• Simple vector search isn't enough — "What did Alice do last spring?" requires temporal reasoning, not just semantic similarity
• Facts get disconnected — Knowing "Alice works at Google" and "Google is in Mountain View" should let you answer "Where does Alice work?" even if you never stored that directly
• Agents need opinions — A coding assistant that remembers "the user prefers functional programming" should weigh that when making recommendations
• Context matters — The same information means different things to different agents with different personalities

Hindsight solves these problems with a memory system designed specifically for AI agents.

What Hindsight Does

graph LR
    subgraph Clients
        A[Python Client]
        B[Node.js Client]
        C[CLI]
        D[AI Assistants]
    end

    subgraph Hindsight Server
        E[HTTP API]
        F[MCP API]
    end

    A --> E
    B --> E
    C --> E
    D --> F

    E --> G[Memory Engine]
    F --> G

    G --> H[(PostgreSQL + pgvector)]

Store conversations and documents → Search with multi-strategy retrieval → Think with personality-aware reasoning

Architecture

graph TB
    subgraph Input
        I1[Raw Text]
        I2[Conversations]
        I3[Documents]
    end

    subgraph Ingestion
        E1[LLM Extraction]
        E2[Entity Resolution]
        E3[Graph Construction]
    end

    subgraph Storage
        S1[World Facts]
        S2[Agent Facts]
        S3[Opinions]
        S4[Entity Graph]
    end

    subgraph Retrieval
        R1[Semantic Search]
        R2[Keyword Search]
        R3[Graph Traversal]
        R4[Temporal Search]
        R5[RRF Fusion]
        R6[Cross-Encoder Rerank]
    end

    subgraph Output
        O1[Search Results]
        O2[Think Response]
    end

    I1 --> E1
    I2 --> E1
    I3 --> E1
    E1 --> E2
    E2 --> E3
    E3 --> S1
    E3 --> S2
    E3 --> S3
    E3 --> S4

    S1 --> R1
    S1 --> R2
    S4 --> R3
    S1 --> R4

    R1 --> R5
    R2 --> R5
    R3 --> R5
    R4 --> R5
    R5 --> R6
    R6 --> O1
    R6 --> O2

Key Components

Three Memory Networks

Hindsight separates memories by type for epistemic clarity:

Network	What it stores	Example
World	Objective facts received	"Alice works at Google"
Agent	Agent's own actions	"I recommended Python to Bob"
Opinion	Formed beliefs + confidence	"Python is best for ML" (0.85)

Multi-Strategy Retrieval (TEMPR)

Four search strategies run in parallel:

graph LR
    Q[Query] --> S[Semantic]
    Q --> K[Keyword]
    Q --> G[Graph]
    Q --> T[Temporal]

    S --> RRF[RRF Fusion]
    K --> RRF
    G --> RRF
    T --> RRF

    RRF --> CE[Cross-Encoder]
    CE --> R[Results]

Strategy	Best for
Semantic	Conceptual similarity, paraphrasing
Keyword (BM25)	Names, technical terms, exact matches
Graph	Related entities, indirect connections
Temporal	"last spring", "in June", time ranges

Personality Framework (CARA)

Agents have Big Five personality traits that influence opinion formation:

Trait	Low	High
Openness	Prefers proven methods	Embraces new ideas
Conscientiousness	Flexible, spontaneous	Systematic, organized
Extraversion	Independent	Collaborative
Agreeableness	Direct, analytical	Diplomatic, harmonious
Neuroticism	Calm, optimistic	Risk-aware, cautious

The bias_strength parameter (0-1) controls how much personality influences opinions.

Client-Server Interaction

sequenceDiagram
    participant C as Client
    participant A as Hindsight API
    participant DB as PostgreSQL

    C->>A: store("Alice works at Google")
    A->>A: Extract facts & entities
    A->>A: Build graph links
    A->>DB: Store memory units
    A-->>C: Success

    C->>A: search("What does Alice do?")
    A->>DB: 4-way parallel search
    A->>A: RRF fusion + rerank
    A-->>C: Ranked results

    C->>A: think("Tell me about Alice")
    A->>DB: Retrieve relevant memories
    A->>A: Generate with personality
    A-->>C: Response + sources

Next Steps

• Quick Start — Get up and running in 60 seconds

• Architecture — Deep dive into ingestion, storage, and graph construction

• Retrieval — How TEMPR's 4-way search works

• Personality — CARA framework and opinion formation

• Ingest Data — Store memories, conversations, and documents

• Search Facts — Multi-strategy retrieval

• Think — Personality-aware response generation

• Server Deployment — Deploy with Docker Compose, Helm, or pip

• Development Guide — Set up a local development environment