docs: add AI SDK integration documentation (#304)

* docs: add AI SDK integration documentation

- Add comprehensive AI SDK documentation in docs/sdks/integrations/ai-sdk.md
  - Detailed description of all three memory tools (retain, recall, reflect)
  - Complete parameter documentation and return types
  - Advanced usage patterns (streaming, multi-user, ToolLoopAgent)
  - HTTP client example for zero-dependency usage
  - TypeScript types and API reference
  - Best practices and system prompt examples

- Update AI SDK README to brief quickstart with link to docs
  - Single source of truth: comprehensive docs in documentation site
  - README now focuses on quick setup and points to full docs
  - Maintains features list and basic example for npm page

* fix

Author: nicoloboschi

hindsight-dev/hindsight_dev/sync_cookbook.py

@@ -0,0 +1,122 @@
+---
+sidebar_position: 8
+---
+
+# Hindsight AI SDK - Personal Chef
+
+
+:::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/taste-ai)
+:::
+
+
+A personal food assistant demonstrating three key Hindsight integrations using the [Vercel AI SDK v6](https://sdk.vercel.ai/docs).
+
+## Architecture: Single Bank with User Tags
+
+This demo uses a **single Hindsight bank** (`taste-ai`) for all users, with each user's data tagged using `user:${username}`.
+
+```typescript
+// All users share the same bank
+const BANK_ID = 'taste-ai';
+
+// Each memory is tagged with the user
+await hindsightTools.retain.execute({
+  bankId: BANK_ID,
+  content: userData,
+  tags: [`user:${username}`],
+});
+```
+
+This architecture enables:
+- **Per-user queries**: Filter by `user:alice` to get personalized results
+- **Aggregated insights**: Query across all users to find popular recipes or common dietary patterns
+- **Simplified management**: One bank to maintain instead of per-user banks
+
+## Three Hindsight Integrations
+
+### 1. Meal Suggestions with Memory Recall & Reflection
+
+Uses `recall` and `reflect` tools with AI SDK's agent-based approach to gather personalized context.
+
+```typescript
+const contextResult = await generateText({
+  model: llmModel,
+  tools: {
+    recall: hindsightTools.recall,
+    reflect: hindsightTools.reflect,
+  },
+  toolChoice: 'auto',
+  prompt: `You are gathering context for personalized ${mealType} recipe suggestions.
+
+Use the recall tool to search for the user's food preferences, dislikes, and recent meals.
+Then use the reflect tool to analyze their dietary patterns and restrictions.
+
+After gathering context, summarize their preferences and recent eating patterns.`,
+});
+```
+
+The AI agent autonomously:
+- Searches memory for cuisine preferences and dietary restrictions
+- Analyzes recent protein consumption for variety
+- Identifies foods to avoid
+
+### 2. Goal Progress Tracking with Mental Models
+
+Uses mental models to automatically maintain updated insights about user progress.
+
+```typescript
+// Create a mental model that auto-refreshes after new meals
+await hindsightTools.createMentalModel.execute({
+  bankId: BANK_ID,
+  mentalModelId: getMentalModelId(username, 'goals'),
+  name: `${username}'s Goal Progress`,
+  sourceQuery: `Analyze ${username}'s dietary goals and eating patterns.
+    Describe their progress towards their stated goals (weight loss, muscle gain, etc.).`,
+  tags: [`user:${username}`],
+  autoRefresh: true, // Refreshes automatically after consolidation
+});
+
+// Query the mental model for current insights
+const result = await hindsightTools.queryMentalModel.execute({
+  bankId: BANK_ID,
+  mentalModelId: mentalModelId,
+});
+```
+
+Mental models automatically:
+- Track progress towards dietary goals
+- Update after each new meal is logged
+- Provide fresh insights without manual refresh
+
+### 3. Language Enforcement with Directives
+
+Uses directives to ensure all responses match user's language preference.
+
+```typescript
+await hindsightClient.createDirective(BANK_ID, {
+  name: `${username}'s Language Preference`,
+  content: `Always respond in ${language}. All suggestions must be in ${language}.`,
+  priority: 100,
+  tags: [`user:${username}`, 'directive:language'],
+});
+```
+
+Directives are automatically injected when mental models generate insights, ensuring consistent language across all interactions.
+
+## Running the Demo
+
+```bash
+npm install
+npm run dev
+```
+
+**Requirements:**
+- Hindsight server running at `http://localhost:8888` (or set `HINDSIGHT_URL`)
+- Node.js 18+
+
+## Learn More
+
+- [Hindsight AI SDK on npm](https://www.npmjs.com/package/@vectorize-io/hindsight-ai-sdk)
+- [AI SDK Documentation](https://sdk.vercel.ai/docs)

hindsight-docs/docs/cookbook/applications/taste-ai.md

@@ -1,39 +1,147 @@
 ---
 sidebar_position: 1
+hide_table_of_contents: true
+pagination_next: null
+pagination_prev: null
+custom_edit_url: null
+sidebar_class_name: hidden-sidebar
 ---
 
 import RecipeCarousel from '@site/src/components/RecipeCarousel';
 
+<div className="cookbook-page">
+
 # Cookbook
 
-Practical patterns, recipes, and complete applications for building with Hindsight.
+Learn how to build with Hindsight through practical examples:
+
+- **[Recipes](#recipes)** - Step-by-step guides and patterns for common use cases
+- **[Applications](#applications)** - Complete, runnable applications demonstrating Hindsight integration
 
 <RecipeCarousel
   title="Recipes"
   items={[
-    { title: "Hindsight Quickstart", href: "/cookbook/recipes/quickstart" },
-    { title: "Per-User Memory", href: "/cookbook/recipes/per-user-memory" },
-    { title: "Support Agent with Shared Knowledge", href: "/cookbook/recipes/support-agent-shared-knowledge" },
-    { title: "Memory with LiteLLM", href: "/cookbook/recipes/litellm-memory-demo" },
-    { title: "Routing Tool Learning", href: "/cookbook/recipes/tool-learning-demo" },
-    { title: "Fitness Coach with Hindsight Memory", href: "/cookbook/recipes/fitness_tracker" },
-    { title: "Healthcare Assistant with Hindsight Memory", href: "/cookbook/recipes/healthcare_assistant" },
-    { title: "Movie Recommendation Assistant with Hindsight Memory", href: "/cookbook/recipes/movie_recommendation" },
-    { title: "Personal AI Assistant with Hindsight Memory", href: "/cookbook/recipes/personal_assistant" },
-    { title: "Personalized Search Agent with Hindsight Memory", href: "/cookbook/recipes/personalized_search" },
-    { title: "Study Buddy with Hindsight Memory", href: "/cookbook/recipes/study_buddy" }
+    {
+      title: "Hindsight Quickstart",
+      href: "/cookbook/recipes/quickstart",
+      description: "Learn the basics: retain, recall, and reflect",
+      tags: { sdk: "hindsight-client", topic: "Quick Start" }
+    },
+    {
+      title: "Per-User Memory",
+      href: "/cookbook/recipes/per-user-memory",
+      description: "Build a chatbot with per-user memory isolation",
+      tags: { sdk: "hindsight-client", topic: "Learning" }
+    },
+    {
+      title: "Support Agent with Shared Knowledge",
+      href: "/cookbook/recipes/support-agent-shared-knowledge",
+      description: "Combine per-user memory with shared product documentation",
+      tags: { sdk: "hindsight-client", topic: "Learning" }
+    },
+    {
+      title: "Memory with LiteLLM",
+      href: "/cookbook/recipes/litellm-memory-demo",
+      description: "Add automatic memory to any LLM app using LiteLLM callbacks",
+      tags: { sdk: "hindsight-litellm", topic: "Quick Start" }
+    },
+    {
+      title: "Routing Tool Learning",
+      href: "/cookbook/recipes/tool-learning-demo",
+      description: "Teach an LLM which tool to use through feedback and memory",
+      tags: { sdk: "hindsight-litellm", topic: "Learning" }
+    },
+    {
+      title: "Fitness Coach with Hindsight Memory",
+      href: "/cookbook/recipes/fitness_tracker",
+      description: "Track workouts, diet, and progress with a personalized fitness coach",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Healthcare Assistant with Hindsight Memory",
+      href: "/cookbook/recipes/healthcare_assistant",
+      description: "A supportive chatbot that remembers patient history and preferences",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Movie Recommendation Assistant with Hindsight Memory",
+      href: "/cookbook/recipes/movie_recommendation",
+      description: "Get personalized movie recommendations that improve over time",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Personal AI Assistant with Hindsight Memory",
+      href: "/cookbook/recipes/personal_assistant",
+      description: "A general-purpose assistant that remembers your life and preferences",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Personalized Search Agent with Hindsight Memory",
+      href: "/cookbook/recipes/personalized_search",
+      description: "Search assistant that learns your location, diet, and lifestyle",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Study Buddy with Hindsight Memory",
+      href: "/cookbook/recipes/study_buddy",
+      description: "Track study sessions, identify knowledge gaps, and get personalized review suggestions",
+      tags: { sdk: "hindsight-client", topic: "Learning" }
+    }
   ]}
 />
 
 <RecipeCarousel
   title="Applications"
   items={[
-    { title: "Chat Memory App", href: "/cookbook/applications/chat-memory" },
-    { title: "Deliveryman Demo", href: "/cookbook/applications/deliveryman-demo" },
-    { title: "Memory Approaches Comparison Demo", href: "/cookbook/applications/hindsight-litellm-demo" },
-    { title: "Tool Learning Demo", href: "/cookbook/applications/hindsight-tool-learning-demo" },
-    { title: "OpenAI Agent + Hindsight Memory Integration", href: "/cookbook/applications/openai-fitness-coach" },
-    { title: "Sanity CMS Blog Memory", href: "/cookbook/applications/sanity-blog-memory" },
-    { title: "Stance Tracker", href: "/cookbook/applications/stancetracker" }
+    {
+      title: "Chat Memory App",
+      href: "/cookbook/applications/chat-memory",
+      description: "Real-time chat app with per-user memory using Groq and Hindsight",
+      tags: { sdk: "hindsight-client", topic: "Chat" }
+    },
+    {
+      title: "Deliveryman Demo",
+      href: "/cookbook/applications/deliveryman-demo",
+      description: "Delivery agent simulation demonstrating learning through mental models",
+      tags: { sdk: "hindsight-client", topic: "Learning" }
+    },
+    {
+      title: "Memory Approaches Comparison Demo",
+      href: "/cookbook/applications/hindsight-litellm-demo",
+      description: "Interactive comparison of memory approaches: none, full history, and semantic retrieval",
+      tags: { sdk: "hindsight-litellm", topic: "Quick Start" }
+    },
+    {
+      title: "Tool Learning Demo",
+      href: "/cookbook/applications/hindsight-tool-learning-demo",
+      description: "Show how Hindsight helps LLMs learn which tool to use when names are ambiguous",
+      tags: { sdk: "hindsight-litellm", topic: "Learning" }
+    },
+    {
+      title: "OpenAI Agent + Hindsight Memory Integration",
+      href: "/cookbook/applications/openai-fitness-coach",
+      description: "Fitness coach using OpenAI Assistants with Hindsight as memory backend",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Sanity CMS Blog Memory",
+      href: "/cookbook/applications/sanity-blog-memory",
+      description: "Sync Sanity CMS blog posts to Hindsight for semantic search and AI insights",
+      tags: { sdk: "hindsight-client", topic: "Learning" }
+    },
+    {
+      title: "Stance Tracker",
+      href: "/cookbook/applications/stancetracker",
+      description: "Track political candidates' stances over time with automated web scraping",
+      tags: { sdk: "hindsight-client", topic: "Recommendation" }
+    },
+    {
+      title: "Hindsight AI SDK - Personal Chef",
+      href: "/cookbook/applications/taste-ai",
+      description: "Personal food assistant with AI SDK v6 showcasing recall, mental models, and directives",
+      tags: { sdk: "@vectorize-io/hindsight-ai-sdk", topic: "Recommendation" }
+    }
   ]}
 />
+
+</div>