diff --git a/hindsight-docs/docusaurus.config.ts b/hindsight-docs/docusaurus.config.ts index efdff4ba..1aeab455 100644 --- a/hindsight-docs/docusaurus.config.ts +++ b/hindsight-docs/docusaurus.config.ts @@ -201,23 +201,10 @@ const config: Config = { className: 'navbar-item-sdks', }, { - to: '/api-reference', + to: '/faq', position: 'left', - label: 'API Reference', - className: 'navbar-item-api', - }, - { - type: 'doc', - docId: 'cookbook/index', - position: 'left', - label: 'Cookbook', - className: 'navbar-item-cookbook', - }, - { - to: '/blog', - position: 'left', - label: 'Blog', - className: 'navbar-item-blog', + label: 'FAQ', + className: 'navbar-item-faq', }, { to: '/changelog', @@ -225,6 +212,27 @@ const config: Config = { label: 'Changelog', className: 'navbar-item-changelog', }, + { + type: 'dropdown', + label: 'Resources', + position: 'left', + className: 'navbar-item-resources', + items: [ + { + type: 'doc', + docId: 'cookbook/index', + label: 'Cookbook', + }, + { + to: '/blog', + label: 'Blog', + }, + { + to: '/api-reference', + label: 'API Reference', + }, + ], + }, { href: 'https://ui.hindsight.vectorize.io/signup', position: 'right', diff --git a/hindsight-docs/src/pages/faq.md b/hindsight-docs/src/pages/faq.md new file mode 100644 index 00000000..a0e1e5c7 --- /dev/null +++ b/hindsight-docs/src/pages/faq.md @@ -0,0 +1,151 @@ +--- +title: Frequently Asked Questions +description: Common questions and answers about Hindsight +hide_table_of_contents: true +--- + +# Frequently Asked Questions + +### What is Hindsight and how does it differ from RAG? + +Hindsight is an agent memory system that provides long-term memory for AI agents using biomimetic data structures. Unlike traditional RAG (Retrieval-Augmented Generation), Hindsight: + +- **Stores structured facts** instead of raw document chunks +- **Builds mental models** that consolidate knowledge over time +- **Uses graph-based relationships** between entities and concepts +- **Supports temporal reasoning** with time-aware retrieval +- **Enables disposition-aware reflection** for nuanced reasoning + +For a detailed comparison, see [RAG vs Memory](/developer/rag-vs-hindsight). + +--- + +### Why use Hindsight instead of other solutions? + +Hindsight is purpose-built for agent memory with unique advantages: + +- **State-of-the-art accuracy**: Ranked #1 LongMemEval benchmarks for agent memory (see [details](https://benchmarks.hindsight.vectorize.io/)) +- **Built on proven technology**: PostgreSQL - battle-tested, reliable, and widely understood +- **Cloud-native architecture**: Designed for modern cloud deployments with horizontal scalability +- **Flexible deployment**: Self-host or use Hindsight Cloud - works with any LLM provider +- **True long-term memory**: Builds mental models that consolidate knowledge over time, not just retrieval +- **Graph-based reasoning**: Understands relationships between entities and concepts for richer context +- **Production-ready**: Scales to millions of memories with 50-500ms recall latency +- **Developer-friendly**: Simple APIs (retain, recall, reflect), SDKs for Python/TypeScript/Go/Rust, integrations with LiteLLM/Vercel AI SDK + +Unlike vector databases (just search) or RAG systems (document retrieval), Hindsight provides **living memory** that evolves with your users. + +--- + +### Which LLM providers are supported? + +Hindsight supports: +- **OpenAI** +- **Anthropic** +- **Google Gemini** +- **Groq** +- **Ollama** (local models) +- **LM Studio** (local models) +- **Any OpenAI-compatible provider** (Together AI, Fireworks, DeepInfra, etc.) +- **Any Anthropic-compatible provider** + +**Using local models with Ollama:** +```bash +HINDSIGHT_API_LLM_PROVIDER=ollama +HINDSIGHT_API_LLM_MODEL=llama3.1 +HINDSIGHT_API_LLM_BASE_URL=http://localhost:11434 +``` + +**Using local models with LM Studio:** +```bash +HINDSIGHT_API_LLM_PROVIDER=lmstudio +HINDSIGHT_API_LLM_MODEL=your-model-name +HINDSIGHT_API_LLM_BASE_URL=http://localhost:1234/v1 +``` + +Configure your provider using the `HINDSIGHT_API_LLM_PROVIDER` environment variable. See [Configuration](/developer/configuration) and [Models](/developer/models) for details. + +--- + +### Do I need to host my own infrastructure? + +No! You have two options: + +1. **Hindsight Cloud** - Fully managed service at [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io) +2. **Self-hosted** - Deploy on your own infrastructure using Docker or direct installation + +See [Installation](/developer/installation) for self-hosting instructions. + +--- + +### What are the minimum system requirements for self-hosting? + +For running the Hindsight API server locally: +- Python 3.11+ +- 4GB RAM minimum (8GB recommended for production) +- LLM API key (OpenAI, Anthropic, etc.) or local LLM setup + +See [Installation](/developer/installation) for setup instructions. + +--- + +### How do I isolate user data? + +A **memory bank** is an isolated memory store (like a "brain") that contains its own memories, entities, relationships, and optional disposition traits (skepticism, literalism, empathy). Banks are completely isolated from each other with no data leakage. + +There are two approaches for multi-user applications: + +**1. Per-user memory banks** (recommended for most use cases) +- Create one bank per user (e.g., `bank_id="user-123"`) +- Easiest setup and strongest data isolation +- Perfect for per-user queries and personalization +- Each bank can have unique disposition traits and background context +- **Limitation**: Cannot perform cross-user analysis (e.g., "What is the most mentioned topic across all users?") + +**2. Single bank with tags** (for applications needing aggregated insights) +- Use one bank for the entire application +- Tag memories with user identifiers during retain (e.g., `tags={"user_id": "user-123"}`) +- Filter by tags during recall/reflect for per-user queries +- **Advantage**: Enables both per-user AND cross-user queries (e.g., analyze specific users or aggregate across all users) + +Choose per-user banks for simplicity and privacy, or single bank with tags if you need holistic reasoning across users. See [Memory Banks](/developer/api/memory-banks) for management details. + +--- +### What's the difference between retain, recall, and reflect? + +Hindsight has three core operations: + +- **Retain**: Store data (facts, entities, relationships) +- **Recall**: Search and retrieve raw memory data based on a query +- **Reflect**: Use an AI agent to answer a query using retrieved memories + +See [Operations](/developer/api/operations) for API details. + +--- + +### When should I use mental models? + +**Mental models** are consolidated knowledge patterns synthesized from individual facts over time. Use them when you need: + +- Higher-level understanding beyond raw facts (e.g., "User prefers functional programming patterns") +- Long-term behavioral patterns (e.g., "Customer is price-sensitive but values quality") +- Context for AI agent reasoning during **reflect** operations + +Mental models are automatically built during retain and used by reflect to provide richer, more contextual responses. See [Mental Models](/developer/api/mental-models). + +--- + + +### What's the typical latency for recall operations? + +Typical latencies: +- **Without reranking**: 50-100ms +- **With reranking**: 200-500ms (depends on reranker model and installation) + +See [Performance](/developer/performance) for tuning options. + + + +## Still have questions? + +Join our [Slack community](https://join.slack.com/t/hindsight-space/shared_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg) or report issues on [GitHub](https://github.com/vectorize-io/hindsight/issues).