From a70b97a871555ea45a5c45afb3b8905d8c19be0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Wed, 3 Dec 2025 17:09:31 +0100 Subject: [PATCH 1/3] fix docker cp image build on ci --- .github/workflows/test.yml | 19 +--- .../engine/retain/fact_extraction.py | 26 ++++- hindsight-clients/python/README.md | 2 +- hindsight-clients/typescript/README.md | 100 ++++++++++++------ 4 files changed, 92 insertions(+), 55 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c59d9a16f8..e02f35c8f5 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -129,24 +129,7 @@ jobs: test-api: runs-on: ubuntu-latest needs: [build-python-packages] - - services: - postgres: - image: pgvector/pgvector:pg16 - env: - POSTGRES_USER: postgres - POSTGRES_PASSWORD: postgres - POSTGRES_DB: hindsight_test - options: >- - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - - 5432:5432 - env: - HINDSIGHT_API_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/hindsight_test HINDSIGHT_API_LLM_PROVIDER: groq HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }} HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b @@ -170,4 +153,4 @@ jobs: - name: Run tests working-directory: ./hindsight-api - run: uv run pytest tests -v --ignore=tests/test_fact_extraction_quality.py + run: uv run pytest tests -v diff --git a/hindsight-api/hindsight_api/engine/retain/fact_extraction.py b/hindsight-api/hindsight_api/engine/retain/fact_extraction.py index c18ed5e19f..68822a89f9 100644 --- a/hindsight-api/hindsight_api/engine/retain/fact_extraction.py +++ b/hindsight-api/hindsight_api/engine/retain/fact_extraction.py @@ -16,6 +16,24 @@ from ..llm_wrapper import OutputTooLongError, LLMConfig +def _sanitize_text(text: str) -> str: + """ + Sanitize text by removing invalid Unicode surrogate characters. + + Surrogate characters (U+D800 to U+DFFF) are used in UTF-16 encoding + but cannot be encoded in UTF-8. They can appear in Python strings + from improperly decoded data (e.g., from JavaScript or broken files). + + This function removes unpaired surrogates to prevent UnicodeEncodeError + when the text is sent to the LLM API. + """ + if not text: + return text + # Remove surrogate characters (U+D800 to U+DFFF) using regex + # These are invalid in UTF-8 and cause encoding errors + return re.sub(r'[\ud800-\udfff]', '', text) + + class Entity(BaseModel): """An entity extracted from text.""" text: str = Field( @@ -470,6 +488,10 @@ async def _extract_facts_from_chunk( max_retries = 2 last_error = None + # Sanitize input text to prevent Unicode encoding errors (e.g., unpaired surrogates) + sanitized_chunk = _sanitize_text(chunk) + sanitized_context = _sanitize_text(context) if context else 'none' + # Build user message with metadata and chunk content in a clear format # Format event_date with day of week for better temporal reasoning event_date_formatted = event_date.strftime('%A, %B %d, %Y') # e.g., "Monday, June 10, 2024" @@ -477,10 +499,10 @@ async def _extract_facts_from_chunk( Chunk: {chunk_index + 1}/{total_chunks} Event Date: {event_date_formatted} ({event_date.isoformat()}) -Context: {context if context else 'none'} +Context: {sanitized_context} Text: -{chunk}""" +{sanitized_chunk}""" for attempt in range(max_retries): try: diff --git a/hindsight-clients/python/README.md b/hindsight-clients/python/README.md index a8fc4b947b..d5451b99f0 100644 --- a/hindsight-clients/python/README.md +++ b/hindsight-clients/python/README.md @@ -36,4 +36,4 @@ response = client.reflect( ## Documentation -For full documentation, visit [hindsight.dev](https://hindsight.dev). +For full documentation, visit [hindsight](https://github.com/vectorize-io/hindsight). diff --git a/hindsight-clients/typescript/README.md b/hindsight-clients/typescript/README.md index 46d47cd9c7..2b561eecda 100644 --- a/hindsight-clients/typescript/README.md +++ b/hindsight-clients/typescript/README.md @@ -1,57 +1,89 @@ -# @hindsight/client +# Hindsight TypeScript Client -TypeScript client for Hindsight - Semantic memory system with personality-driven thinking. - -**Auto-generated from OpenAPI spec** - provides type-safe access to all Hindsight API endpoints. +TypeScript client library for the Hindsight API. ## Installation ```bash -npm install @hindsight/client +npm install @vectorize-io/hindsight-client # or -yarn add @hindsight/client +yarn add @vectorize-io/hindsight-client ``` -## Quick Start +## Usage ```typescript -import { OpenAPI, MemoryStorageService, ReasoningService } from '@hindsight/client'; +import { HindsightClient } from '@vectorize-io/hindsight-client'; -// Configure API base URL -OpenAPI.BASE = 'http://localhost:8888'; +const client = new HindsightClient({ baseUrl: 'http://localhost:8888' }); -// Store memory -await MemoryStorageService.putApiPutPost({ - agent_id: 'user123', - content: 'Alice loves machine learning' -}); +// Retain information +await client.retain('my-bank', 'Alice works at Google in Mountain View.'); + +// Recall memories +const results = await client.recall('my-bank', 'Where does Alice work?'); + +// Reflect and get an opinion +const response = await client.reflect('my-bank', 'What do you think about Alice\'s career?'); +``` + +## API Reference + +### `retain(bankId, content, options?)` -// Think (generate answer with personality) -const response = await ReasoningService.thinkApiThinkPost({ - agent_id: 'user123', - query: 'What does Alice think about AI?', - thinking_budget: 50 +Store a single memory. + +```typescript +await client.retain('my-bank', 'User prefers dark mode', { + timestamp: new Date(), + context: 'Settings conversation', + metadata: { source: 'chat' } }); +``` -console.log(response.text); +### `retainBatch(bankId, items, options?)` + +Store multiple memories in batch. + +```typescript +await client.retainBatch('my-bank', [ + { content: 'Alice loves hiking' }, + { content: 'Alice visited Paris last summer' } +], { async: true }); ``` -## Available Services +### `recall(bankId, query, options?)` -- `MemoryStorageService` - Store and retrieve facts -- `SearchService` - Semantic and temporal search -- `ReasoningService` - Personality-driven thinking -- `VisualizationService` - Memory graphs and statistics -- `ManagementService` - Agent profiles and configuration -- `DocumentsService` - Document tracking +Recall memories matching a query. -All services are fully typed with TypeScript interfaces. +```typescript +const results = await client.recall('my-bank', 'What are Alice\'s hobbies?', { + budget: 'mid' +}); +``` + +### `reflect(bankId, query, options?)` + +Generate a contextual answer using the bank's identity and memories. + +```typescript +const response = await client.reflect('my-bank', 'What should I do this weekend?', { + budget: 'low' +}); +console.log(response.text); +``` + +### `createBank(bankId, options)` -## Development +Create or update a memory bank with personality. -Auto-generated from `openapi.json`. See [RELEASE.md](../../RELEASE.md) for regeneration instructions. +```typescript +await client.createBank('my-bank', { + name: 'My Assistant', + background: 'A helpful assistant that remembers everything.' +}); +``` -## Links +## Documentation -- [GitHub Repository](https://github.com/vectorize-io/hindsight) -- [Full Documentation](https://github.com/vectorize-io/hindsight/blob/main/README.md) +For full documentation, visit [hindsight](https://github.com/vectorize-io/hindsight). From 0a601931e51502f75ad5122be65d1053b92236c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Wed, 3 Dec 2025 18:20:57 +0100 Subject: [PATCH 2/3] fix docker --- docker/standalone/Dockerfile | 4 +++- uv.lock | 6 +++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docker/standalone/Dockerfile b/docker/standalone/Dockerfile index 1eb9ab43de..3c09ac887e 100644 --- a/docker/standalone/Dockerfile +++ b/docker/standalone/Dockerfile @@ -74,8 +74,10 @@ WORKDIR /app COPY --from=sdk-builder /app/sdk /app/sdk # Install Control Plane dependencies +# Use npm install instead of npm ci to resolve platform-specific native bindings +# (package-lock.json may have been generated on a different platform) COPY hindsight-control-plane/package*.json ./ -RUN npm ci +RUN npm install # Copy Control Plane source COPY hindsight-control-plane/ ./ diff --git a/uv.lock b/uv.lock index c4a605ee7f..9f91d4db86 100644 --- a/uv.lock +++ b/uv.lock @@ -1141,7 +1141,7 @@ provides-extras = ["test"] [[package]] name = "hindsight-api" -version = "0.0.12" +version = "0.0.14" source = { editable = "hindsight-api" } dependencies = [ { name = "alembic" }, @@ -1243,7 +1243,7 @@ dev = [ [[package]] name = "hindsight-client" -version = "0.0.12" +version = "0.0.14" source = { editable = "hindsight-clients/python" } dependencies = [ { name = "aiohttp" }, @@ -1275,7 +1275,7 @@ provides-extras = ["test"] [[package]] name = "hindsight-dev" -version = "0.0.12" +version = "0.0.14" source = { editable = "hindsight-dev" } dependencies = [ { name = "hindsight-api" }, From 38a6e6f0fcb84f502a2dd67bfeec40d87ec1f636 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Wed, 3 Dec 2025 18:35:42 +0100 Subject: [PATCH 3/3] fix docker again --- .github/workflows/test.yml | 19 ++ docker/standalone/Dockerfile | 10 +- .../docs/developer/api/installation.md | 4 +- .../docs/developer/api/quickstart.md | 2 +- hindsight-docs/docs/developer/index.md | 2 +- hindsight-docs/docs/developer/installation.md | 300 +++--------------- hindsight-docs/docs/developer/performance.md | 2 +- 7 files changed, 73 insertions(+), 266 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e02f35c8f5..08aefd0124 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -53,6 +53,25 @@ jobs: working-directory: ./hindsight-clients/typescript run: npm run build + build-docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install dependencies + working-directory: ./hindsight-docs + run: npm ci + + - name: Build docs + working-directory: ./hindsight-docs + run: npm run build + build-rust-cli: runs-on: ubuntu-latest diff --git a/docker/standalone/Dockerfile b/docker/standalone/Dockerfile index 3c09ac887e..d87de95471 100644 --- a/docker/standalone/Dockerfile +++ b/docker/standalone/Dockerfile @@ -74,13 +74,15 @@ WORKDIR /app COPY --from=sdk-builder /app/sdk /app/sdk # Install Control Plane dependencies -# Use npm install instead of npm ci to resolve platform-specific native bindings -# (package-lock.json may have been generated on a different platform) -COPY hindsight-control-plane/package*.json ./ +# Only copy package.json (not package-lock.json) to ensure npm installs +# correct platform-specific native bindings for lightningcss/tailwindcss +COPY hindsight-control-plane/package.json ./ RUN npm install -# Copy Control Plane source +# Copy Control Plane source (excluding node_modules via .dockerignore) COPY hindsight-control-plane/ ./ +# Remove package-lock.json to avoid conflicts with installed native bindings +RUN rm -f package-lock.json # Link SDK (temporary for build) RUN cd /app/sdk && npm link && cd /app && npm link @vectorize-io/hindsight-client diff --git a/hindsight-docs/docs/developer/api/installation.md b/hindsight-docs/docs/developer/api/installation.md index 0e8ac8e4fc..9a6ccb23f3 100644 --- a/hindsight-docs/docs/developer/api/installation.md +++ b/hindsight-docs/docs/developer/api/installation.md @@ -39,7 +39,7 @@ pip install hindsight-client npm install @hindsight/client ``` -**Requires:** A running Hindsight server (see [Server Deployment](/developer/server) for setup). +**Requires:** A running Hindsight server (see [Server Deployment](/developer/installation) for setup). @@ -120,4 +120,4 @@ hindsight --version ## Next Steps - [**Quick Start**](./quickstart) — Get running in 60 seconds -- [**Server Deployment**](/developer/server) — Production setup options +- [**Server Deployment**](/developer/installation) — Production setup options diff --git a/hindsight-docs/docs/developer/api/quickstart.md b/hindsight-docs/docs/developer/api/quickstart.md index 4e3aa39ebd..27f0cb3f5d 100644 --- a/hindsight-docs/docs/developer/api/quickstart.md +++ b/hindsight-docs/docs/developer/api/quickstart.md @@ -123,4 +123,4 @@ hindsight reflect my-bank "Tell me about Alice" - [**Recall**](./recall) — Search and retrieval strategies - [**Reflect**](./reflect) — Personality-aware reasoning - [**Memory Banks**](./memory-banks) — Configure personality and background -- [**Server Options**](/developer/server) — Production deployment +- [**Server Options**](/developer/installation) — Production deployment diff --git a/hindsight-docs/docs/developer/index.md b/hindsight-docs/docs/developer/index.md index 938bf51cb5..ffad7280b4 100644 --- a/hindsight-docs/docs/developer/index.md +++ b/hindsight-docs/docs/developer/index.md @@ -121,4 +121,4 @@ The `bias_strength` parameter (0-1) controls how much personality influences opi - [**Operations**](/developer/api/operations) — Monitor async tasks ### Deployment -- [**Server Setup**](/developer/server) — Deploy with Docker Compose, Helm, or pip +- [**Server Setup**](/developer/installation) — Deploy with Docker Compose, Helm, or pip diff --git a/hindsight-docs/docs/developer/installation.md b/hindsight-docs/docs/developer/installation.md index 90466dcb5e..e7ac50c8e4 100644 --- a/hindsight-docs/docs/developer/installation.md +++ b/hindsight-docs/docs/developer/installation.md @@ -1,56 +1,33 @@ # Installation -Hindsight can be deployed in multiple ways depending on your infrastructure and requirements. This guide covers all installation methods and explains the core dependencies. +Hindsight can be deployed in three ways depending on your infrastructure and requirements. -## Dependencies +## Prerequisites -Hindsight has two core dependencies that you need to provide: +### PostgreSQL with pgvector -### 1. PostgreSQL Database +Hindsight requires PostgreSQL with the **pgvector** extension for vector similarity search: -**Why PostgreSQL?** - -Hindsight uses PostgreSQL with the **pgvector** extension to store and query semantic memories efficiently: - -- **Vector search**: pgvector enables fast approximate nearest neighbor (ANN) search using HNSW indexes -- **Full-text search**: PostgreSQL's GIN indexes provide BM25-ranked text search -- **Graph storage**: Entity relationships are stored using relational tables -- **ACID compliance**: Ensures data consistency for memory operations -- **Temporal queries**: Native date/time support for temporal reasoning - -**Requirements**: - PostgreSQL 14+ (recommended: 16+) - pgvector extension installed -- ~2GB+ RAM for small deployments, 4GB+ for production - -### 2. LLM Provider +- ~2GB+ RAM for small deployments -**Why an LLM?** +### LLM Provider -Hindsight uses Large Language Models for several critical operations: +You need an LLM API key for fact extraction, entity resolution, and answer generation: -- **Fact extraction**: Converting raw text into structured semantic facts during retention -- **Entity resolution**: Identifying and linking entities across memories -- **Temporal parsing**: Understanding time references in natural language -- **Opinion generation**: Creating personality-based opinions during reflection -- **Answer generation**: Synthesizing responses from retrieved memories - -**Performance Impact**: The LLM is the primary bottleneck for **write operations (retention)**. See [Performance](./performance.md) for details on optimizing throughput. - -**Supported Providers**: -- **Groq**: Fast inference, high throughput (recommended for production) +- **Groq** (recommended): Fast inference, high throughput - **OpenAI**: GPT-4, GPT-4o, GPT-4 Mini - **Anthropic**: Claude 3.5 Sonnet, Haiku -- **Ollama**: Run models locally (llama3.1, mixtral, etc.) -- **Any OpenAI-compatible API**: Custom endpoints +- **Ollama**: Run models locally -## Installation Methods +--- -### Docker Compose (Recommended) +## Docker **Best for**: Quick start, development, small deployments -**Why use this?**: Bundles all dependencies (PostgreSQL with pgvector, API server, optional Control Plane) in a single command. +Docker Compose bundles all dependencies (PostgreSQL with pgvector, API server, Control Plane) in a single command. ```bash # Clone the repository @@ -68,43 +45,35 @@ cd docker ./start.sh ``` -**What you get**: +**Services started**: - **API Server**: http://localhost:8888 - **Control Plane** (Web UI): http://localhost:3000 - **Swagger UI**: http://localhost:8888/docs -- **PostgreSQL**: Runs in container with pgvector extension **Management**: ```bash -# Stop services -cd docker && ./stop.sh - -# Clean all data (WARNING: deletes all memories) -cd docker && ./clean.sh - -# View logs -docker-compose logs -f api -docker-compose logs -f postgres +./stop.sh # Stop services +./clean.sh # Delete all data ``` -### Helm Chart (Kubernetes) +--- -**Best for**: Production deployments, auto-scaling, cloud environments +## Helm / Kubernetes -**Why use this?**: Kubernetes-native deployment with proper resource management, health checks, and auto-scaling capabilities. +**Best for**: Production deployments, auto-scaling, cloud environments ```bash # Add Hindsight Helm repository helm repo add hindsight https://vectorize-io.github.io/hindsight helm repo update -# Install with basic configuration +# Install with built-in PostgreSQL helm install hindsight hindsight/hindsight \ --set api.llm.provider=groq \ --set api.llm.apiKey=gsk_xxxxxxxxxxxx \ --set postgresql.enabled=true -# Or use your own PostgreSQL +# Or use external PostgreSQL helm install hindsight hindsight/hindsight \ --set api.llm.provider=groq \ --set api.llm.apiKey=gsk_xxxxxxxxxxxx \ @@ -112,248 +81,65 @@ helm install hindsight hindsight/hindsight \ --set api.database.url=postgresql://user:pass@postgres.example.com:5432/hindsight ``` -**What you need**: +**Requirements**: - Kubernetes cluster (GKE, EKS, AKS, or self-hosted) -- kubectl configured - Helm 3+ -- External PostgreSQL with pgvector (recommended) or use built-in PostgreSQL -See the [Helm chart documentation](https://github.com/vectorize-io/hindsight/tree/main/deploy/helm) for advanced configuration. +See the [Helm chart documentation](https://github.com/vectorize-io/hindsight/tree/main/helm) for advanced configuration. -### pip install (Python Package) +--- -**Best for**: Custom deployments, development, integration into existing Python applications +## Bare Metal (pip) -**Why use this?**: Maximum flexibility. Runs as a Python application with embedded PostgreSQL (pg0) by default, or connects to your own database. +**Best for**: Custom deployments, integration into existing Python applications -#### Install +### Install ```bash -# Install the all-in-one package pip install hindsight-all - -# Verify installation -hindsight-api --version ``` -#### Run with Embedded Database (pg0) +### Run with Embedded Database -**Best for**: Development, testing, single-machine deployments +For development and testing, Hindsight can run with an embedded PostgreSQL (pg0): ```bash -# Configure LLM provider export HINDSIGHT_API_LLM_PROVIDER=groq export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx -# Start the server - uses embedded pg0 hindsight-api ``` -**What happens**: -- Creates `~/.hindsight/data/` directory for database storage -- Downloads ML models on first run (~500MB) -- Starts API server on http://localhost:8888 -- Ready to use - no external dependencies needed! - -**Limitations**: -- Single process only (no horizontal scaling) -- Lower performance than dedicated PostgreSQL -- Not recommended for production +This creates a database in `~/.hindsight/data/` and starts the API on http://localhost:8888. -#### Run with External PostgreSQL +### Run with External PostgreSQL -**Best for**: Production, high-performance deployments +For production, connect to your own PostgreSQL instance: ```bash -# Configure database export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight - -# Configure LLM -export HINDSIGHT_API_LLM_PROVIDER=groq -export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx - -# Start the server -hindsight-api -``` - -**Requirements**: -- PostgreSQL 14+ with pgvector extension -- Database must already exist -- pgvector extension must be enabled: `CREATE EXTENSION vector;` - -#### CLI Options - -```bash -hindsight-api --help - -# Common options -hindsight-api --port 9000 # Custom port (default: 8888) -hindsight-api --host 127.0.0.1 # Bind to localhost only -hindsight-api --workers 4 # Multiple worker processes -hindsight-api --mcp # Enable MCP server -hindsight-api --log-level debug # Verbose logging -hindsight-api --reload # Auto-reload on code changes (dev) -``` - -### Cloud Managed Services - -**Best for**: Production with minimal ops overhead - -You can deploy Hindsight to cloud platforms using their managed services: - -#### AWS - -```bash -# Use RDS PostgreSQL with pgvector -# Deploy via ECS, EKS, or EC2 -# Example: ECS with Fargate -docker build -t hindsight-api . -aws ecr get-login-password | docker login --username AWS -docker push your-ecr-repo/hindsight-api -# Deploy via ECS task definition -``` - -**Required AWS Services**: -- **RDS PostgreSQL** with pgvector extension -- **ECS/EKS** for container orchestration -- **Secrets Manager** for API keys -- **ALB** for load balancing (optional) - -#### Google Cloud - -```bash -# Use Cloud SQL PostgreSQL with pgvector -# Deploy via Cloud Run or GKE -gcloud run deploy hindsight \ - --image gcr.io/your-project/hindsight-api \ - --set-env-vars HINDSIGHT_API_DATABASE_URL=... \ - --set-secrets HINDSIGHT_API_LLM_API_KEY=... -``` - -**Required GCP Services**: -- **Cloud SQL PostgreSQL** with pgvector -- **Cloud Run** or **GKE** for deployment -- **Secret Manager** for API keys - -#### Supabase - -**Simplest cloud deployment** - Supabase provides PostgreSQL with pgvector built-in: - -```bash -# 1. Create a Supabase project at supabase.com -# 2. Get your database URL from Settings > Database -# 3. Deploy API server with DATABASE_URL - -export HINDSIGHT_API_DATABASE_URL=postgresql://postgres:password@db.xxxxxxxxxxxx.supabase.co:5432/postgres export HINDSIGHT_API_LLM_PROVIDER=groq export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx hindsight-api ``` -## Choosing an Installation Method - -| Method | Best For | Pros | Cons | -|--------|----------|------|------| -| **Docker Compose** | Development, small deployments | Easy setup, all dependencies included | Not scalable, single host | -| **Helm/Kubernetes** | Production, auto-scaling | Scalable, cloud-native, resilient | Complex setup, K8s knowledge required | -| **pip install** | Development, custom integration | Flexible, Python-native, embedded DB option | Manual dependency management | -| **Cloud Services** | Production with managed infrastructure | Minimal ops, auto-scaling, managed DB | Higher cost, cloud lock-in | - -## Post-Installation - -### Verify Installation - -```bash -# Check API server health -curl http://localhost:8888/health - -# List banks (should return empty array initially) -curl http://localhost:8888/api/v1/banks - -# View API documentation -open http://localhost:8888/docs -``` - -### First Steps - -1. **Create your first bank**: - ```bash - curl -X POST http://localhost:8888/api/v1/banks/my-first-bank \ - -H "Content-Type: application/json" \ - -d '{"name": "My First Bank"}' - ``` - -2. **Retain your first memory**: - ```bash - curl -X POST http://localhost:8888/api/v1/banks/my-first-bank/retain \ - -H "Content-Type: application/json" \ - -d '{"items": [{"content": "The Eiffel Tower is in Paris."}]}' - ``` - -3. **Recall the memory**: - ```bash - curl -X POST http://localhost:8888/api/v1/banks/my-first-bank/recall \ - -H "Content-Type: application/json" \ - -d '{"query": "Where is the Eiffel Tower?"}' - ``` - -### Next Steps - -- **Configure** your deployment: [Configuration](./configuration.md) -- **Understand ML models**: [Models](./models.md) -- **Monitor performance**: [Metrics](./metrics.md) -- **Optimize for production**: [Performance](./performance.md) - -## Troubleshooting - -### PostgreSQL Connection Issues - -```bash -# Test database connection -psql "$HINDSIGHT_API_DATABASE_URL" - -# Verify pgvector extension -psql -c "SELECT * FROM pg_extension WHERE extname = 'vector';" - -# Enable pgvector if missing -psql -c "CREATE EXTENSION IF NOT EXISTS vector;" -``` - -### LLM Provider Issues - -```bash -# Test Groq API key -curl https://api.groq.com/openai/v1/models \ - -H "Authorization: Bearer $HINDSIGHT_API_LLM_API_KEY" - -# Test OpenAI API key -curl https://api.openai.com/v1/models \ - -H "Authorization: Bearer $HINDSIGHT_API_LLM_API_KEY" -``` - -### Port Already in Use - -```bash -# Find process using port 8888 -lsof -i :8888 - -# Kill the process -kill -9 +**Note**: The database must exist and have pgvector enabled (`CREATE EXTENSION vector;`). -# Or use a different port -hindsight-api --port 9000 -``` - -### Model Download Issues +### CLI Options ```bash -# Models are downloaded to ~/.cache/huggingface/ -# Clear cache and retry -rm -rf ~/.cache/huggingface/ -hindsight-api # Will re-download models +hindsight-api --port 9000 # Custom port (default: 8888) +hindsight-api --host 127.0.0.1 # Bind to localhost only +hindsight-api --workers 4 # Multiple worker processes +hindsight-api --mcp # Enable MCP server +hindsight-api --log-level debug # Verbose logging ``` --- -For installation issues not covered here, please [open an issue](https://github.com/your-repo/hindsight/issues) on GitHub. +## Next Steps + +- [Configuration](./configuration.md) — Environment variables and settings +- [Models](./models.md) — ML models and providers +- [Metrics](./metrics.md) — Monitoring and observability diff --git a/hindsight-docs/docs/developer/performance.md b/hindsight-docs/docs/developer/performance.md index 620e32cb11..e08f3278f7 100644 --- a/hindsight-docs/docs/developer/performance.md +++ b/hindsight-docs/docs/developer/performance.md @@ -309,7 +309,7 @@ Hindsight has been evaluated on the LoComo (Long Context Memory) benchmark: - **Average recall latency**: 400-600ms (mid budget) - **Average reflect latency**: 1500-2500ms (end-to-end) -See [benchmarks README](../../benchmarks/README.md) for detailed results. +See the [GitHub repository](https://github.com/vectorize-io/hindsight/tree/main/hindsight-dev/benchmarks) for detailed benchmark results. ### Performance Metrics