vectorize-io/hindsight-cookbook

1. Repository shape

This is not a single product codebase; it is a cookbook of standalone demos centered on the Hindsight memory service. Each folder under applications/ is an independent example app, while notebooks/ contains smaller tutorial-style integrations.

2. Primary architectural boundary: Hindsight as external memory

The core dependency across the repo is the Hindsight API/service running separately from these examples. Most apps send conversation events, observations, or domain facts to Hindsight for retain / recall / reflect-style memory, then read that memory back to influence future responses.

3. Notebook layer: direct, minimal integrations

The Jupyter notebooks are the simplest architecture: a notebook cell drives the whole flow, calling Hindsight and an LLM inline. These are good for diagramming the request → memory retrieval → model response loop without extra app layers.

4. Simple Python agent demos

Examples like agno-memory, pydantic-ai-memory, smolagents-memory, crewai-memory, openai-fitness-coach, and others are single-process Python agents. Their structure is usually:

- one agent script

- a small requirements.txt

- a memory helper/seed script

- optional tool wrappers

The important boundary is between the agent runtime and the external Hindsight memory store.

5. Next.js-based chat apps

Apps such as chat-memory and chat-memory-cloud use a typical Next.js frontend + API route structure:

- app/components/* handles chat UI

- app/api/chat/route.ts orchestrates requests

- lib/hindsight.ts and lib/llm.ts / lib/groq.ts isolate model and memory calls

The backend logic is intentionally thin; the main flow is UI → API route → LLM + Hindsight → streamed/returned answer.

6. Multi-platform bot architecture

chat-sdk-multi-platform extends the same pattern to Discord + webhook-based platforms. Instead of a browser chat UI, the ingress points are:

- Discord gateway route

- platform webhook route

Shared bot/memory logic lives in lib/bot.ts and lib/hindsight.ts, so the architecture is “multiple event sources, one shared conversation/memory core.”

7. Full-stack Python backend + TypeScript frontend demos

cable-co, claims-iq, and deliveryman-demo use a more explicit separation:

- a Python backend under backend/app

- a TypeScript/React frontend under frontend

- WebSocket hooks for live state updates

The backend contains service layers such as agent_service.py and memory_service.py, while the frontend renders operational panels, controls, and live telemetry. This is the most diagram-worthy “UI ↔ backend orchestration ↔ memory” pattern in the repo.

8. Operational event stream as a first-class UI concern

In the live demo apps, the frontend is not just a chat window. Components like control bars, knowledge panels, mental-model panels, activity logs, metrics, and pipeline visualizations indicate a streaming operational dashboard. The backend pushes state changes over WebSocket, and the UI reflects the agent’s intermediate reasoning, not only final answers.

9. Domain-specific pipelines and external data sources

stancetracker is a richer pipeline app: it combines scheduled scraping, stance extraction, RAG, vectorization, and a database layer. Its architecture includes:

- API routes for sessions, scheduler, and stance management

- lib/ modules for scraping, extraction, scheduling, and vector/search integration

- SQL schema and DB access under lib/db

This example is best drawn as an ingestion pipeline feeding a search/memory system, not as a simple chat app.

10. Content sync / ingestion app

sanity-blog-memory is a synchronization pipeline rather than an interactive agent. It pulls content from Sanity CMS, transforms it, and syncs it into Hindsight via src/sync.ts, hindsight-client.ts, and sanity-client.ts. The main boundary is CMS source → sync job → Hindsight memory.

11. Benchmarking and experiments as separate lanes

deliveryman-demo includes benchmark services, configs, tests, and a separate frontend-benchmark game-style UI built with Phaser. It also has an experiments/ folder for retraining and retrieval tests. This means the repo contains both product demos and evaluation harnesses, which should be diagrammed as separate from runtime user paths.

12. Cross-cutting local storage and session state

Frontends use local stores (sessionStore, claimsStore, gameStore) and hooks (useWebSocket, useToast) for ephemeral UI state. This local state is intentionally separate from long-term memory, which is handled externally by Hindsight. That distinction is important: UI state is local and transient; memory is shared and persistent.

13. Infrastructure and tooling

Most apps are self-contained and bring their own runtime:

- Python apps: requirements.txt, run.sh, sometimes FastAPI-style app structure

- Node/Next apps: package.json, tsconfig, next.config.*

- React/Vite apps: frontend/ with Vite config

- Docker and .env.example files where external services are required

The repo also has a GitHub Actions workflow to test notebooks, showing that notebooks are treated as part of the supported surface area.

14. How to draw the architecture at repo level

The clearest high-level diagram is:

- User interfaces: notebooks, web UIs, chat UIs, bot endpoints

- App orchestration layer: Python services or Next.js API routes

- Agent/model layer: tool use, retrieval, reasoning, pipelines

- Shared memory layer: Hindsight service

- External data/services: LLM providers, Discord/webhooks, CMS, scraping targets, databases

Each example plugs these pieces together differently, but the recurring design is always event-driven orchestration with Hindsight as the durable memory boundary.