doc: update cookbook (#284)

* fix: sync-cookbook now supports new cookbook repo layout

Cookbook repository changed structure:
- Applications moved from root to applications/ subdirectory
- Notebooks remain in notebooks/ directory (unchanged)

Updated sync script to:
- Look for apps in applications/* instead of root/*
- Update GitHub URLs to include applications/ path
- Add safety check if applications/ dir doesn't exist

* doc: update cookbook

* doc: update cookbook

* doc: update cookbook

Author: nicoloboschi

hindsight-dev/hindsight_dev/sync_cookbook.py

@@ -4,14 +4,14 @@
 
 - Clones the cookbook repo to a temp directory
 - Converts notebooks/*.ipynb → docs/cookbook/recipes/*.md
-- Converts app directories (with README.md) → docs/cookbook/applications/*.md
+- Converts applications/*/ directories (with README.md) → docs/cookbook/applications/*.md
 - Updates sidebars.ts with the new entries
 
 Usage: sync-cookbook (after installing hindsight-dev)
 
 Conventions in cookbook repo:
 - notebooks/*.ipynb → Recipes (use cases, tutorials)
-- Directories with README.md at root → Applications (complete apps)
+- applications/*/ directories with README.md → Applications (complete apps)
 - Notebook title extracted from first # heading in first markdown cell
 - App title extracted from first # heading in README.md
 """
@@ -236,7 +236,13 @@ def process_applications(cookbook_dir: Path, apps_dir: Path) -> list[dict]:
     """Process application directories with README.md."""
     apps = []
 
-    for entry in sorted(cookbook_dir.iterdir()):
+    # Applications are now in the applications/ subdirectory
+    applications_dir = cookbook_dir / "applications"
+    if not applications_dir.exists():
+        print("  No applications directory found")
+        return apps
+
+    for entry in sorted(applications_dir.iterdir()):
         if not entry.is_dir() or entry.name in IGNORE_DIRS:
             continue
 
@@ -253,7 +259,7 @@ def process_applications(cookbook_dir: Path, apps_dir: Path) -> list[dict]:
         readme_content = readme_path.read_text()
 
         # Create application page with frontmatter
-        app_url = f"https://github.com/vectorize-io/hindsight-cookbook/tree/main/{entry.name}"
+        app_url = f"https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/{entry.name}"
 
         frontmatter = f"""---
 sidebar_position: {len(apps) + 1}

hindsight-docs/docs/cookbook/applications/chat-memory.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 1
+---
+
+# Chat Memory App
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/chat-memory)
+:::
+
+
+A demo chat application that uses Groq's `qwen/qwen3-32b` model with Hindsight for persistent per-user memory.
+
+## Features
+
+- 🧠 **Persistent Memory**: Each user gets their own memory bank that remembers conversations
+- 🚀 **Fast AI**: Powered by Groq's high-speed inference
+- 🎯 **Per-User Context**: Isolated memory per user with automatic context retrieval
+- 💬 **Real-time Chat**: Instant responses with memory-augmented context
+
+## Setup
+
+### 1. Start Hindsight API
+
+First, start the Hindsight API server using Docker:
+
+```bash
+export GROQ_API_KEY=your_groq_api_key_here
+
+# Start Hindsight with Groq as the LLM provider
+docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=groq \
+  -e HINDSIGHT_API_LLM_API_KEY=$GROQ_API_KEY \
+  -e HINDSIGHT_API_LLM_MODEL="openai/gpt-oss-20b" \
+  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+- **API**: http://localhost:8888
+- **Control Plane UI**: http://localhost:9999
+
+### 2. Configure Environment
+
+Copy your Groq API key to the environment file:
+
+```bash
+# Update .env.local with your Groq API key
+echo "GROQ_API_KEY=your_groq_api_key_here" > .env.local
+echo "HINDSIGHT_API_URL=http://localhost:8888" >> .env.local
+```
+
+If you don't have one, you can get a free Groq API key here: https://console.groq.com/home
+
+### 3. Install Dependencies
+
+```bash
+npm install
+```
+
+### 4. Run the App
+
+```bash
+npm run dev
+```
+
+Open http://localhost:3000 in your browser.
+
+## How It Works
+
+1. **User Identity**: Each browser session gets a unique user ID
+2. **Memory Bank Creation**: First message creates a personal memory bank in Hindsight
+3. **Context Retrieval**: Before responding, relevant memories are retrieved
+4. **Memory Augmented Response**: Groq generates responses with memory context
+5. **Conversation Storage**: Each conversation is stored for future context
+
+## Architecture
+
+```
+User Message
+     ↓
+Next.js API Route (/api/chat)
+     ↓
+Hindsight.recall() → Get relevant memories
+     ↓
+Groq API → Generate response with memory context
+     ↓
+Hindsight.retain() → Store conversation
+     ↓
+Response to User
+```
+
+## Memory Bank Structure
+
+Each user gets their own isolated memory bank with:
+- **Name**: "Chat Memory for [userId]"
+- **Background**: Conversational AI assistant context
+- **Disposition**: Empathetic (4), Low Skepticism (2), Balanced Literalism (3)
+
+## Try It Out
+
+1. **First Conversation**: Tell the assistant about yourself
+   - "Hi! I'm a software engineer from San Francisco. I love Python and machine learning."
+
+2. **Second Conversation**: Ask what it remembers
+   - "What do you know about me?"
+   - "What programming languages do I like?"
+
+3. **Context Building**: Continue sharing preferences
+   - "I prefer VS Code over other editors"
+   - "I'm working on a React project"
+
+4. **Memory Verification**: Visit the Hindsight Control Plane at http://localhost:9999 to see stored memories
+
+## Development
+
+- **Groq Model**: Uses `qwen/qwen3-32b` for fast, high-quality responses
+- **Memory Storage**: Automatic conversation retention with context categorization
+- **Memory Retrieval**: Semantic search with 2048 token budget for relevant context

hindsight-docs/docs/cookbook/applications/deliveryman-demo.md

@@ -0,0 +1,145 @@
+---
+sidebar_position: 2
+---
+
+# Deliveryman Demo
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/deliveryman-demo)
+:::
+
+
+A delivery agent simulation that demonstrates Hindsight's long-term memory capabilities. An AI agent navigates a multi-building office complex to deliver packages, learning employee locations and optimal paths over time through mental models.
+
+## Prerequisites
+
+- Python 3.11+
+- Node.js 18+
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+## Setup (Fresh Environment)
+
+### 1. Clone Repositories
+
+```bash
+# Clone Hindsight (memory engine)
+git clone https://github.com/anthropics/hindsight.git
+
+# Clone the cookbook (contains this demo)
+git clone https://github.com/anthropics/hindsight-cookbook.git
+```
+
+### 2. Start Hindsight API
+
+```bash
+cd hindsight
+cp .env.example .env
+```
+
+Edit `.env` with your LLM configuration:
+
+```bash
+HINDSIGHT_API_LLM_PROVIDER=groq
+HINDSIGHT_API_LLM_API_KEY=<your-groq-api-key>
+HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-120b
+HINDSIGHT_API_HOST=0.0.0.0
+HINDSIGHT_API_PORT=8888
+HINDSIGHT_API_ENABLE_OBSERVATIONS=true
+
+# Retain extraction settings (improves employee/location extraction)
+HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom
+HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS="Delivery agent. Remember employee locations, building layout, and optimal paths."
+
+# Embedded database storage
+PG0_DATA_DIR=/tmp/hindsight-data
+```
+
+Start the API:
+
+```bash
+./scripts/dev/start-api.sh
+# Runs on http://localhost:8888
+```
+
+### 3. Start Hindsight Control Plane (Optional)
+
+The control plane provides a web UI for inspecting memory banks, facts, and mental models.
+
+```bash
+cd hindsight
+./scripts/dev/start-control-plane.sh
+# Runs on a dynamic port (check terminal output)
+```
+
+### 4. Start Demo Backend
+
+```bash
+cd hindsight-cookbook/deliveryman-demo/backend
+
+# Create virtual environment and install dependencies
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Create `backend/.env`:
+
+```bash
+OPENAI_API_KEY=<your-openai-api-key>
+GROQ_API_KEY=<your-groq-api-key>
+HINDSIGHT_API_URL=http://localhost:8888
+LLM_MODEL=openai/gpt-4o
+```
+
+Start the backend:
+
+```bash
+./run.sh
+# Or manually:
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws wsproto --reload
+```
+
+**Note:** The `--ws wsproto` flag is required for WebSocket support. Without it, connections will fail with error 1006.
+
+### 5. Start Demo Frontend
+
+```bash
+cd hindsight-cookbook/deliveryman-demo/frontend
+npm install
+npm run dev
+# Runs on http://localhost:5173
+```
+
+### 6. Open the Demo
+
+Navigate to http://localhost:5173 in your browser.
+
+## How It Works
+
+1. The agent receives a delivery task (e.g., "Deliver Package #3954 to Victor Huang")
+2. It navigates a multi-building complex with floors, elevators, and sky bridges
+3. Along the way it encounters employees and learns their locations
+4. After each delivery, the conversation is sent to Hindsight via the **retain** API
+5. Hindsight extracts facts (employee locations, building layout) and builds **mental models**
+6. On subsequent deliveries, the agent queries Hindsight to recall what it learned
+
+## Architecture
+
+```
+Browser (5173) → Frontend (React + Phaser)
+                    ↓ WebSocket
+                 Backend (8000) → FastAPI + Delivery Agent
+                    ↓ HTTP
+                 Hindsight API (8888) → Memory Engine + PostgreSQL
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| WebSocket error 1006 | Restart backend with `--ws wsproto` flag |
+| Mental models missing employees | Check `HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom` is set |
+| Hindsight connection refused | Verify Hindsight API is running on port 8888 |
+| Frontend shows "Disconnected" | Check backend is running on port 8000 |