Hindsight (58k★): How Agent Memory Actually Learns

When agents repeat tasks, they perform better if they remember past experience.

But "memory" is not all the same thing. Simple log storage and learning memory are fundamentally different.

Hindsight implements the latter. With over 58,000 stars on GitHub, this project designs agent memory not as simple data storage but as biomimetic data structures — inspired by how human memory works.

Biomimetic Memory Structure

Hindsight's memory models the human memory system.

Human Memory Model          Hindsight Implementation
─────────────────          ────────────────────────
World Facts      ──▶       World facts (facts, definitions)
Experiences      ──▶       Experiences (events, episodes)
Observations     ──▶       Observations (patterns, notes)
Mental Models    ──▶       Mental models (abstractions, rules)

Each memory type has a different lifecycle and search strategy.

World facts:    Permanent, frequently updated
Experiences:    Semi-permanent, context-dependent
Observations:   Semi-permanent, pattern-based
Mental models:  Long-term, rarely updated

Retain → Recall → Reflect: Three Operations

Hindsight's core API consists of three operations.

Retain  → Store in memory (write)
Recall  → Retrieve relevant memories (read)
Reflect → Deep analysis of existing memories (analyze)

Retain: Storage

from hindsight import HindsightClient

client = HindsightClient()

# Store a world fact
await client.retain("my-bank", "Alice loves hiking in Yosemite")

# Store an experience
await client.retain("my-bank", "Alice asked about mortgage rates on 2026-10-15")

Memories are organized in banks, separated per user or project.

Recall: Search — Four Parallel Strategies

The most technically interesting part of Hindsight is Recall. It uses four parallel search strategies and merges results into a single ranking.

Recall Query: "What does Alice like?"
  │
  ├── Semantic Search (vector) ──┐
  ├── Keyword Search (BM25)      ├── Reciprocal Rank Fusion ──▶ Final ranking
  ├── Graph Search (entities)    │
  └── Temporal Search (time) ────┘

Each strategy's role:

Reciprocal Rank Fusion (RRF)

The method for merging results from four strategies is Reciprocal Rank Fusion.

RRF score = Σ 1 / (k + rank_i)

Where k is a constant (typically 60), and rank_i is the position
from each strategy.

Example:
  Memory A: Semantic #1, Keyword #5 → 1/61 + 1/65 = 0.031
  Memory B: Semantic #3, Keyword #2 → 1/63 + 1/62 = 0.032

  Memory B wins slightly — it ranks high across both strategies.

RRF uses only relative rankings, not absolute scores from each strategy. This allows fair comparison of strategies with different scoring systems.

Reflect: Deep Analysis

Reflect is a deep analysis operation based on existing memories. It goes beyond simple retrieval — it identifies relationships between memories and generates new insights.

# Analyze Alice's behavior patterns
reflection = await client.reflect("my-bank", """
  Analyze Alice's financial behavior patterns.
  What are her priorities and concerns?
""")

# Result: "Alice shows strong interest in home buying,
#          is sensitive to interest rate changes.
#          Loan-related inquiries have increased since Oct 2026."

This feature is a unique differentiator of Hindsight that simple RAG systems don't have.

Architecture: Self-Hostable

Hindsight can be deployed in three ways: Docker, pip (bare metal), and embedded DB (pg0).

Docker deployment:
  hindsight-server (main service)
  ├── Retention Service (storage)
  ├── Recall Service (search)
  ├── Reflect Service (analysis)
  └── Storage Backend (PostgreSQL + pgvector)

Embedded mode:
  pip install hindsight-all
  # Use directly in Python without a server

LiteLLM integration supports 100+ models, allowing Hindsight to work across various LLM ecosystems.

60+ Integrations — The Power of Ecosystem

Hindsight integrates with Claude Code, Codex, Cursor, LangGraph, CrewAI, n8n, and 60+ other tools.

                ┌── Claude Code
                ├── Codex
                ├── Cursor
                ├── LangGraph
                ├── CrewAI
                ├── n8n
User data ──────┤ ... (60+ integrations)
                ├── OpenHands
                ├── AutoGen
                ├── LangChain
                ├── LlamaIndex
                └── ...

This integration ecosystem is the primary driver behind Hindsight's 58k stars.

Limitations and Considerations

1. Graph search overhead: Enabling Graph Search requires entity extraction and graph construction, which has significant initial setup cost.
2. Memory growth: Repeated Retain calls without cleanup will cause unbounded memory growth. A retention policy is needed.
3. Reflect cost: Reflect operations involve LLM calls, so frequent execution incurs costs.
4. Self-hosted complexity: Docker deployment is relatively straightforward, but bare metal (pip) installation requires platform-specific attention. Intel Macs need hindsight-all-slim.

Developer Takeaway

When designing agent memory, three questions matter most.

1. What to remember? World facts, experiences, observations, mental models — each requires different lifecycles and search strategies.

2. How to find it? A single search strategy (vector only) is insufficient. Parallel 4-strategy search (Semantic + Keyword + Graph + Temporal) produces better results in real use cases.

3. How to learn? Beyond simple retrieval, the Reflect operation analyzes relationships between memories so agents can achieve true "learning."

Hindsight provides all three. Its 58k stars represent not just popularity but a clear market demand for agent memory systems.

• GitHub
• Documentation
• Paper
• Benchmarks