doc: add go client examples (#380)

* doc: add go client examples

* doc: add go client examples

Author: nicoloboschi

hindsight-dev/hindsight_dev/sync_cookbook.py

@@ -489,8 +489,10 @@ def convert_tags_to_structured(tags: list[str]) -> dict[str, str]:
     - sdk: Package name (detected from tag values)
     - topic: anything else (Learning, Quick Start, etc.)
 
-    If sdk tag starts with '@vectorize-io', it's Node.js.
-    Otherwise assumes Python.
+    Supported languages:
+    - Node.js: packages starting with '@vectorize-io'
+    - Go: packages ending with '-go' or containing 'go-'
+    - Python: everything else
     """
     structured = {}
     topic_tags = {"Learning", "Quick Start", "Recommendation", "Chat"}

hindsight-docs/docs/cookbook/applications/go-memory-service.md

@@ -0,0 +1,102 @@
+---
+sidebar_position: 3
+---
+
+# Go Memory-Augmented API
+
+
+:::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/go-memory-service)
+:::
+
+
+A Go HTTP microservice demonstrating per-user memory isolation with Hindsight. Remembers each user's tech stack, problems solved, and preferences to provide personalized assistance.
+
+## Features
+
+- 🔐 **Per-User Isolation**: Each user gets their own memory bank
+- 🧠 **Context-Aware Responses**: Uses recall + reflect for personalized answers
+- 🏃 **Fire-and-Forget Memory**: Background goroutines store interactions without blocking responses
+- 🏷️ **Tag-Based Partitioning**: Organize memories by type (projects, debugging, preferences)
+
+## Setup
+
+### 1. Start Hindsight
+
+```bash
+export OPENAI_API_KEY=your-key
+
+docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  -e HINDSIGHT_API_LLM_MODEL=o3-mini \
+  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+### 2. Run the service
+
+```bash
+go run main.go
+```
+
+### 3. Try it out
+
+```bash
+# Store memories
+curl -s localhost:8080/learn -d '{
+  "user_id": "alice",
+  "content": "I am building a Go microservice with gRPC and PostgreSQL",
+  "tags": ["project"]
+}'
+
+curl -s localhost:8080/learn -d '{
+  "user_id": "alice",
+  "content": "I prefer structured logging with slog over zerolog",
+  "tags": ["preferences"]
+}'
+
+# Ask questions (uses recall + reflect)
+curl -s localhost:8080/ask -d '{
+  "user_id": "alice",
+  "query": "What tech stack am I using?"
+}' | jq .
+
+# Raw memory recall
+curl -s "localhost:8080/recall/alice?q=database" | jq .
+```
+
+## API Endpoints
+
+- `POST /learn` - Store new information for a user
+- `POST /ask` - Ask a question using the user's memories
+- `GET /recall/{userID}?q=query` - Direct memory recall
+- `GET /health` - Health check
+
+## Key Patterns
+
+**Per-User Banks**: Each user gets an isolated memory bank (`user-alice`, `user-bob`)
+
+**Async Memory Storage**: Interactions are stored in background goroutines:
+
+```go
+go func() {
+    bgCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+
+    retainReq := hindsight.RetainRequest{
+        Items: []hindsight.MemoryItem{{
+            Content: interaction,
+            Context: *hindsight.NewNullableString(hindsight.PtrString("Q&A interaction")),
+        }},
+    }
+    client.MemoryAPI.RetainMemories(bgCtx, bankID).RetainRequest(retainReq).Execute()
+}()
+```
+
+**Tag-Based Filtering**: Partition memories within a bank by type for scoped retrieval
+
+## Learn More
+
+- [Go SDK Documentation](https://hindsight.vectorize.io/sdks/go)
+- [Hindsight Documentation](https://hindsight.vectorize.io)

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Memory Approaches Comparison Demo

hindsight-docs/docs/cookbook/applications/hindsight-tool-learning-demo.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Tool Learning Demo

hindsight-docs/docs/cookbook/applications/openai-fitness-coach.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # OpenAI Agent + Hindsight Memory Integration

hindsight-docs/docs/cookbook/applications/sanity-blog-memory.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Sanity CMS Blog Memory

hindsight-docs/docs/cookbook/applications/stancetracker.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Stance Tracker

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Hindsight AI SDK - Personal Chef

hindsight-docs/docs/cookbook/index.mdx

@@ -105,6 +105,12 @@ Learn how to build with Hindsight through practical examples:
       description: "Delivery agent simulation demonstrating learning through mental models",
       tags: { sdk: "hindsight-client", topic: "Learning" }
     },
+    {
+      title: "Go Memory-Augmented API",
+      href: "/cookbook/applications/go-memory-service",
+      description: "Go HTTP microservice with per-user memory banks for a developer knowledge assistant",
+      tags: { sdk: "hindsight-go", topic: "Learning" }
+    },
     {
       title: "Memory Approaches Comparison Demo",
       href: "/cookbook/applications/hindsight-litellm-demo",

hindsight-docs/examples/api/documents.mjs

@@ -50,7 +50,7 @@ const apiClient = createClient(createConfig({ baseUrl: 'http://localhost:8888' }
 // Get document to expand context from recall results
 const { data: doc, error } = await sdk.getDocument({
     client: apiClient,
-    path: { bank_id: 'my-bank', document_id: 'meeting-2024-03-15' }
+    path: { bank_id: 'my-bank', document_id: 'meeting-2024-03-15-section-1' }
 });
 
 if (error) {
@@ -68,7 +68,7 @@ console.log(`Created: ${doc.created_at}`);
 // Delete document and all its memories
 const { data: deleteResult } = await sdk.deleteDocument({
     client: apiClient,
-    path: { bank_id: 'my-bank', document_id: 'meeting-2024-03-15' }
+    path: { bank_id: 'my-bank', document_id: 'meeting-2024-03-15-section-1' }
 });
 
 console.log(`Deleted ${deleteResult.memory_units_deleted} memories`);