a706905653
* feat(skill): validate links, strip images, include openapi.json and changelog - Add post-processing step to rewrite Docusaurus site-root paths (e.g. /developer/foo) to proper relative .md paths within the skill - Strip markdown and HTML images from all generated files since assets are not bundled with the skill - Copy hindsight-docs/static/openapi.json into references/openapi.json and map /api-reference links to it - Include changelog.md from src/pages/ alongside faq and best-practices - Add final validation step that fails the build if any link still points outside the skill directory * ci: run generate-docs-skill in verify-generated-files job * fix(skill): strip unresolvable site-root links instead of leaving them broken * fix(skill): write file when images stripped but no links rewritten * chore(skill): regenerate with fixed links, stripped images, changelog and openapi * fix(skill): handle changelog as directory, add agno/hermes integrations, rebase on main
120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
---
|
|
name: hindsight-docs
|
|
description: Complete Hindsight documentation for AI agents. Use this to learn about Hindsight architecture, APIs, configuration, and best practices.
|
|
---
|
|
|
|
# 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)
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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.
|