Hindsight Documentation Skill

Complete technical documentation for Hindsight - a biomimetic memory system for AI agents.

When to Use This Skill

Use this skill when you need to:

• Understand Hindsight architecture and core concepts

• Learn about retain/recall/reflect operations

• Configure memory banks and dispositions

• Set up the Hindsight API server (Docker, Kubernetes, pip)

• Integrate with Python/Node.js/Rust SDKs

• Understand retrieval strategies (semantic, BM25, graph, temporal)

• Debug issues or optimize performance

• Review API endpoints and parameters

• Find cookbook examples and recipes

Documentation Structure

All documentation is in references/ organized by category:

references/

├── best-practices.md # START HERE — missions, tags, formats, anti-patterns

├── faq.md            # Common questions and decisions

├── changelog/        # Release history and version changes (index.md + integrations/)

├── openapi.json      # Full OpenAPI spec — endpoint schemas, request/response models

├── developer/

│   ├── api/          # Core operations: retain, recall, reflect, memory banks

│   └── *.md          # Architecture, configuration, deployment, performance

├── sdks/

│   ├── *.md          # Python, Node.js, CLI, embedded

│   └── integrations/ # LiteLLM, AI SDK, OpenClaw, MCP, skills

└── cookbook/

    ├── recipes/      # Usage patterns and examples

    └── applications/ # Full application demos

How to Find Documentation

1. Find Files by Pattern (use Glob tool)

# Core API operations

references/developer/api/*.md

# SDK documentation

references/sdks/*.md

references/sdks/integrations/*.md

# Cookbook examples

references/cookbook/recipes/*.md

references/cookbook/applications/*.md

# Find specific topics

references/**/configuration.md

references/**/*python*.md

references/**/*deployment*.md

2. Search Content (use Grep tool)

# Search for concepts

pattern: "disposition"        # Memory bank configuration

pattern: "graph retrieval"    # Graph-based search

pattern: "helm install"       # Kubernetes deployment

pattern: "document_id"        # Document management

pattern: "HINDSIGHT_API_"     # Environment variables

# Search in specific areas

path: references/developer/api/

pattern: "POST /v1"           # Find API endpoints

path: references/cookbook/

pattern: "def |async def "    # Find Python examples

3. Read Full Documentation (use Read tool)

references/developer/api/retain.md

references/sdks/python.md

references/cookbook/recipes/per-user-memory.md

Start Here: Best Practices

Before reading API docs, read the best practices guide. It covers practical rules for missions, tags, content format, observation scopes, and anti-patterns — the fastest way to integrate correctly.

references/best-practices.md

Key Concepts

• Memory Banks: Isolated memory stores (one per user/agent)

• Retain: Store memories (auto-extracts facts/entities/relationships)

• Recall: Retrieve memories (4 parallel strategies: semantic, BM25, graph, temporal)

• Reflect: Disposition-aware reasoning using memories

• document_id: Groups messages in a conversation (upsert on same ID)

• Dispositions: Skepticism, literalism, empathy traits (1-5) affecting reflect

• Mental Models: Consolidated knowledge synthesized from facts

Notes

• Code examples are inlined from working examples

• Configuration uses HINDSIGHT_API_* environment variables

• Database migrations run automatically on startup

• Multi-bank queries require client-side orchestration

• Use document_id for conversation evolution (same ID = upsert)

Auto-generated from hindsight-docs/docs/. Run ./scripts/generate-docs-skill.sh to update.