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/
├── 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)

bash
1# Core API operations
2references/developer/api/*.md
3
4# SDK documentation
5references/sdks/*.md
6references/sdks/integrations/*.md
7
8# Cookbook examples
9references/cookbook/recipes/*.md
10references/cookbook/applications/*.md
11
12# Find specific topics
13references/**/configuration.md
14references/**/*python*.md
15references/**/*deployment*.md

2. Search Content (use Grep tool)

bash
1# Search for concepts
2pattern: "disposition"        # Memory bank configuration
3pattern: "graph retrieval"    # Graph-based search
4pattern: "helm install"       # Kubernetes deployment
5pattern: "document_id"        # Document management
6pattern: "HINDSIGHT_API_"     # Environment variables
7
8# Search in specific areas
9path: references/developer/api/
10pattern: "POST /v1"           # Find API endpoints
11
12path: references/cookbook/
13pattern: "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

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.