Compare commits

...
Author SHA1 Message Date
Nicolò Boschi 110aaa4cfd sync 2026-02-26 20:21:59 +01:00
Nicolò Boschi c99a21bf22 doc: changelog and blog post 2026-02-26 20:19:57 +01:00
Nicolò Boschi 4c5a0c261b doc: changelog and blog post 2026-02-26 20:19:52 +01:00
16 changed files with 579 additions and 14 deletions
+155
View File
@@ -0,0 +1,155 @@
---
title: "I Gave My Vercel Chat SDK Bot a Memory. Now It Remembers Users Across Slack and Discord."
authors: [hindsight]
date: 2026-02-26
tags: [chat-sdk, slack, discord, typescript, memory]
---
# I Gave My Vercel Chat SDK Bot a Memory. Now It Remembers Users Across Slack and Discord.
## TL;DR
- Chat bots built with Vercel's Chat SDK forget everything between messages
- `@vectorize-io/hindsight-chat` adds persistent memory with one wrapper function
- Memories cross platforms automatically -- Slack, Discord, Teams, Google Chat
- We built a team assistant that tracks feature requests and bugs across Slack and Discord with shared memory
<!-- truncate -->
---
## The Problem: Your Team Bot Forgets Everything
Your team uses a bot across Slack and Discord. Someone reports a bug in Slack: "The checkout flow is broken on mobile." Someone else mentions a feature request in Discord: "We need dark mode support." A week later, the PM asks the bot: "What are the open issues?" Nothing. The bot has no idea.
This is the default for every Chat SDK bot. Each message is a blank slate. No memory of past conversations, no awareness across platforms, no accumulated knowledge.
Teams work around this by piping everything into Jira or Notion manually. But the context -- the nuance of why something was requested, who cares about it, what was discussed -- gets lost in the handoff.
What if the bot just remembered?
---
## The Fix: One Wrapper, Shared Memory
[`@vectorize-io/hindsight-chat`](https://hindsight.vectorize.io/sdks/integrations/chat) adds a `withHindsightChat()` wrapper to any Chat SDK handler. It automatically recalls relevant memories before your handler runs and retains conversations after.
```
Slack message ─────┐
├─→ withHindsightChat() ─→ recall ─→ your handler ─→ retain
Discord message ───┘ │
Hindsight API
(shared memory)
```
Both platforms share the same memory bank. A bug reported in Slack shows up when someone asks in Discord. Feature requests accumulate across both. The bot builds institutional knowledge over time.
Here's what the core handler looks like:
```typescript
bot.onNewMention(
withHindsightChat(
{
client: hindsight,
bankId: () => 'team-memory',
retain: { enabled: true, tags: ['chat'] },
},
async (thread, message, ctx) => {
const system = [
'You are a team assistant that tracks feature requests, bugs, and decisions.',
'You remember everything the team has discussed across Slack and Discord.',
ctx.memoriesAsSystemPrompt()
? `\nHere is what you know:\n${ctx.memoriesAsSystemPrompt()}`
: '',
].join('\n');
const { text } = await generateText({
model: openai('gpt-4o-mini'),
system,
prompt: message.text,
});
await thread.post(text);
await ctx.retain(`User: ${message.text}\nAssistant: ${text}`);
}
)
);
```
That's the whole handler. The wrapper takes care of recalling memories, formatting them for the LLM, and retaining conversations. You just write the logic. See the [full API reference](https://hindsight.vectorize.io/sdks/integrations/chat) for all configuration options.
---
## What This Looks Like in Practice
**Monday, Slack:**
> **@team-bot** checkout is broken on mobile -- users can't tap the pay button on iOS
The bot acknowledges and retains the bug report.
**Tuesday, Discord:**
> **@team-bot** we really need dark mode, three customers asked about it this week
The bot retains the feature request.
**Wednesday, Slack:**
> **@team-bot** what are the open issues this week?
The bot recalls both the checkout bug and the dark mode request -- even though they came from different platforms, different days, and different people.
No Jira integration. No manual tagging. The bot just remembers.
---
## How It Works
Hindsight isn't a simple vector store. When the bot retains a conversation, Hindsight's pipeline:
1. **Extracts structured facts** -- "checkout is broken on mobile iOS" becomes a fact with entities (checkout, mobile, iOS) and relationships
2. **Builds a knowledge graph** -- entities link across conversations, so "checkout" connects the bug report to any prior discussions about the checkout flow
3. **Recalls with multiple strategies** -- semantic search, keyword matching, graph traversal, and temporal ranking all run in parallel and fuse results
This means the bot doesn't just find messages that look similar to your query. It understands that "open issues" relates to both a bug report and a feature request, even if neither message contained the word "issue."
---
## Memory Isolation
The `bankId` option controls who shares memory:
- **Shared team memory** (`bankId: 'team-memory'`): everyone reads and writes to the same bank. Good for tracking bugs, decisions, and feature requests across the team.
- **Per-user memory** (`bankId: (msg) => msg.author.userId`): each person gets their own bank. Good for personal assistants that remember individual preferences.
- **Per-channel or per-project**: scope the bank ID however you want. One bank per project, per team, per customer.
For the cross-platform use case, a shared bank is the key. Both Slack and Discord write to the same bank, so memories are available everywhere.
---
## Supported Platforms
The Vercel Chat SDK supports Slack, Discord, Microsoft Teams, Google Chat, GitHub, and Linear. The `withHindsightChat()` wrapper works with all of them -- same code, same memory, any combination of platforms.
---
## Try It
The full working example is in the [Hindsight Cookbook](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/chat-sdk-multi-platform). It includes:
- Complete bot with Slack + Discord adapters
- LLM-powered responses with Vercel AI SDK
- Shared Hindsight memory bank
- Discord Gateway route setup
- Environment configuration and setup instructions
Start Hindsight locally or use [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup), clone the cookbook, and you'll have a working cross-platform bot with memory in minutes.
---
## Next Steps
- **Read the docs**: [Chat SDK integration guide](https://hindsight.vectorize.io/sdks/integrations/chat) covers the full API, configuration options, and advanced patterns
- **Clone the cookbook**: [chat-sdk-multi-platform](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/chat-sdk-multi-platform) has the full working example
- **Try Hindsight Cloud**: Skip self-hosting with a [free account](https://ui.hindsight.vectorize.io/signup)
- **Add more platforms**: Teams, Google Chat, GitHub -- same wrapper, same memory
- **Scope memory per team or project**: Use `bankId` to isolate memory for different contexts
@@ -0,0 +1,167 @@
---
sidebar_position: 2
---
# Chat SDK Multi-Platform Bot
:::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-sdk-multi-platform)
:::
A demo chat bot that runs on Slack and Discord simultaneously, sharing a single Hindsight memory bank. Tell the bot something in Slack, ask about it in Discord, and it remembers.
Built with [Vercel Chat SDK](https://github.com/vercel/chat), [Hindsight](https://github.com/vectorize-io/hindsight), and [Vercel AI SDK](https://sdk.vercel.ai).
## Features
- **Cross-platform memory**: Slack and Discord share one memory bank
- **LLM-powered responses**: Uses OpenAI via Vercel AI SDK
- **Auto-recall**: Memories are retrieved before every response
- **Auto-retain**: Conversations are stored automatically
- **One handler, all platforms**: `withHindsightChat()` wraps any Chat SDK handler
## Architecture
```
Slack message ─────┐
├─→ withHindsightChat() ─→ auto-recall ─→ LLM handler ─→ auto-retain
Discord message ───┘ │
Hindsight API
(shared bank)
```
## Setup
### 1. Start Hindsight API
```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=gpt-4o-mini \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
```
- API: http://localhost:8888
- UI: http://localhost:9999
### 2. Set Up Slack
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
2. Under **OAuth & Permissions**, add scopes: `app_mentions:read`, `chat:write`, `channels:history`
3. Install the app to your workspace
4. Copy the **Bot User OAuth Token** and **Signing Secret**
### 3. Set Up Discord
1. Go to [discord.com/developers/applications](https://discord.com/developers/applications) and create a new app
2. Under **Bot**, click **Reset Token** and copy it
3. Enable **Message Content Intent** under Privileged Gateway Intents
4. Under **General Information**, copy the **Application ID** and **Public Key**
5. Under **OAuth2 > URL Generator**, select scopes `bot` + `applications.commands`, permissions: Send Messages, Read Message History
6. Invite the bot to your server using the generated URL
### 4. Configure Environment
```bash
cp .env.example .env.local
# Edit .env.local with your tokens
```
Or create `.env.local` manually:
```bash
# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
# Discord
DISCORD_BOT_TOKEN=...
DISCORD_PUBLIC_KEY=...
DISCORD_APPLICATION_ID=...
DISCORD_MENTION_ROLE_IDS=... # Optional: comma-separated role IDs
# Hindsight
HINDSIGHT_API_URL=http://localhost:8888
# LLM
OPENAI_API_KEY=sk-...
```
### 5. Expose Your Local Server
Discord and Slack need to reach your webhook endpoints:
```bash
ngrok http 3000
```
- Set Slack's **Event Subscriptions > Request URL** to `https://your-ngrok-url/api/webhooks/slack`
- Set Discord's **Interactions Endpoint URL** to `https://your-ngrok-url/api/webhooks/discord`
### 6. Install and Run
```bash
npm install
npm run dev
```
### 7. Start the Discord Gateway
Discord requires a WebSocket connection to receive messages (unlike Slack which pushes events via HTTP). Open this URL in your browser after the dev server starts:
```
http://localhost:3000/api/discord/gateway
```
This keeps a Gateway connection alive for 10 minutes. In production, use a cron job to restart it.
## Try It
1. **Slack**: `@memory-bot I'm building a Rust compiler that targets WebAssembly`
2. Wait a few seconds for Hindsight to index the memory
3. **Discord**: `@memory-bot what am I working on?`
4. The bot recalls the Rust/WebAssembly memory from Slack
## How It Works
The key file is `lib/bot.ts`. Both Slack and Discord adapters are registered with the same Chat instance, and both handlers use `withHindsightChat()` with a shared bank ID:
```typescript
bot.onNewMention(
withHindsightChat(
{
client: hindsight,
bankId: () => BANK_ID, // same bank for all platforms
retain: { enabled: true },
},
async (thread, message, ctx) => {
const system = ctx.memoriesAsSystemPrompt();
// ... generate LLM response with memory context
}
)
);
```
- **`client`**: A `@vectorize-io/hindsight-client` instance pointing at your Hindsight API
- **`bankId`**: Static string or function -- shared bank = cross-platform memory
- **`ctx.memoriesAsSystemPrompt()`**: Formats recalled memories for the LLM system prompt
- **`ctx.retain()`**: Stores conversation content back to the bank
## Bank ID Strategies
| Strategy | Example | Use Case |
|----------|---------|----------|
| Static | `bankId: 'demo'` | Shared team memory |
| Per-user | `bankId: (msg) => msg.author.userId` | Isolated per-user memory |
| Cross-platform identity | Map platform IDs to canonical user | Same user, same bank, any platform |
## License
MIT
@@ -0,0 +1,204 @@
---
sidebar_position: 3
---
# CrewAI + Hindsight Memory
:::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/crewai-memory)
:::
Give your CrewAI crews persistent long-term memory. Run a crew multiple times and watch it build on what it learned in previous runs.
## What This Demonstrates
- **Drop-in memory backend** for CrewAI via `hindsight-crewai`
- **Persistent memory across runs** - crews remember previous research
- **Reflect tool** - agents explicitly reason over past memories
- **Bank missions** - guide how Hindsight organizes memories
## Architecture
```
Run 1: "Research Rust benefits"
├─ Researcher agent ──► Hindsight reflect (no prior memories)
│ ──► produces research findings
├─ Writer agent ────────► summarizes findings
└─ CrewAI auto-stores task outputs to Hindsight
Run 2: "Compare Rust with Go"
├─ Researcher agent ──► Hindsight reflect (recalls Rust research!)
│ ──► builds on prior knowledge
├─ Writer agent ────────► writes comparative summary
└─ Memories accumulate across runs
```
## Prerequisites
1. **Hindsight running**
```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. **OpenAI API key** (for CrewAI's LLM)
```bash
export OPENAI_API_KEY=your-key
```
3. **Install dependencies**
```bash
cd applications/crewai-memory
pip install -r requirements.txt
```
> **Note:** `hindsight-crewai` is not on PyPI — it is installed directly from the
> [Hindsight repo](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/crewai) via git.
## Quick Start
```bash
# First run - the crew has no memories yet
python research_crew.py "What are the benefits of Rust?"
# Second run - the crew remembers the Rust research
python research_crew.py "Compare Rust with Go"
# Third run - the crew has context from both prior runs
python research_crew.py "Which language should I pick for a CLI tool?"
# Reset memory and start fresh
python research_crew.py --reset
```
## How It Works
### 1. Configure Hindsight
```python
from hindsight_crewai import configure, HindsightStorage
configure(hindsight_api_url="http://localhost:8888", verbose=True)
storage = HindsightStorage(
bank_id="research-crew",
mission="Track technology research findings, comparisons, and recommendations.",
)
```
### 2. Add the Reflect Tool
The `HindsightReflectTool` lets agents explicitly query their memories with disposition-aware synthesis:
```python
from hindsight_crewai import HindsightReflectTool
reflect_tool = HindsightReflectTool(bank_id="research-crew", budget="mid")
researcher = Agent(
role="Researcher",
goal="Research topics thoroughly",
backstory="Always use hindsight_reflect to check what you already know.",
tools=[reflect_tool],
)
```
### 3. Wire Up the Crew
```python
from crewai.memory.external.external_memory import ExternalMemory
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, summary_task],
external_memory=ExternalMemory(storage=storage),
)
crew.kickoff()
```
CrewAI automatically:
- **Queries memories** at the start of each task
- **Stores task outputs** after each task completes
## Core Files
| File | Description |
|------|-------------|
| `research_crew.py` | Complete working example with Researcher + Writer agents |
| `requirements.txt` | Python dependencies |
## Customization
### Per-Agent Memory Banks
Give each agent isolated memory:
```python
storage = HindsightStorage(
bank_id="my-crew",
per_agent_banks=True, # "my-crew-researcher", "my-crew-writer"
)
```
### Custom Bank Resolver
Full control over bank naming:
```python
storage = HindsightStorage(
bank_id="my-crew",
bank_resolver=lambda base, agent: f"{base}-{agent.lower()}" if agent else base,
)
```
### Configuration Options
| Parameter | Default | Description |
|-----------|---------|-------------|
| `bank_id` | (required) | Memory bank identifier |
| `mission` | `None` | Guide how Hindsight organizes memories |
| `budget` | `"mid"` | Recall budget: low/mid/high |
| `max_tokens` | `4096` | Max tokens for recall results |
| `per_agent_banks` | `False` | Isolate memory per agent |
| `tags` | `None` | Tags applied when storing |
| `verbose` | `False` | Enable logging |
See the [hindsight-crewai documentation](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/crewai) for the full API reference.
## Common Issues
**"Connection refused"**
- Make sure Hindsight is running on `localhost:8888`
**"OPENAI_API_KEY not set"**
```bash
export OPENAI_API_KEY=your-key
```
**"No module named 'hindsight_crewai'"**
```bash
pip install -r requirements.txt
```
---
**Built with:**
- [CrewAI](https://crewai.com) - Multi-agent orchestration
- [hindsight-crewai](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/crewai) - Hindsight storage backend for CrewAI
- [Hindsight](https://github.com/vectorize-io/hindsight) - Long-term memory for AI agents
@@ -1,5 +1,5 @@
---
sidebar_position: 2
sidebar_position: 4
---
# Deliveryman Demo
@@ -1,5 +1,5 @@
---
sidebar_position: 3
sidebar_position: 5
---
# Go Memory-Augmented API
@@ -29,7 +29,7 @@ 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=gpt-4o-mini \
-e HINDSIGHT_API_LLM_MODEL=o3-mini \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
```
@@ -1,5 +1,5 @@
---
sidebar_position: 4
sidebar_position: 6
---
# Memory Approaches Comparison Demo
@@ -1,5 +1,5 @@
---
sidebar_position: 5
sidebar_position: 7
---
# Tool Learning Demo
@@ -1,5 +1,5 @@
---
sidebar_position: 6
sidebar_position: 8
---
# OpenAI Agent + Hindsight Memory Integration
@@ -1,5 +1,5 @@
---
sidebar_position: 7
sidebar_position: 9
---
# Sanity CMS Blog Memory
@@ -1,5 +1,5 @@
---
sidebar_position: 8
sidebar_position: 10
---
# Stance Tracker
@@ -1,5 +1,5 @@
---
sidebar_position: 9
sidebar_position: 11
---
# Hindsight AI SDK - Personal Chef
+14 -2
View File
@@ -15,8 +15,8 @@ import RecipeCarousel from '@site/src/components/RecipeCarousel';
Learn how to build with Hindsight through practical examples:
- **Recipes** - Step-by-step guides and patterns for common use cases
- **Applications** - Complete, runnable applications demonstrating Hindsight integration
- **[Recipes](#recipes)** - Step-by-step guides and patterns for common use cases
- **[Applications](#applications)** - Complete, runnable applications demonstrating Hindsight integration
<RecipeCarousel
title="Recipes"
@@ -99,6 +99,18 @@ Learn how to build with Hindsight through practical examples:
description: "Real-time chat app with per-user memory using Groq and Hindsight",
tags: { sdk: "hindsight-client", topic: "Chat" }
},
{
title: "Chat SDK Multi-Platform Bot",
href: "/cookbook/applications/chat-sdk-multi-platform",
description: "Multi-platform chat bot with cross-platform memory using Vercel Chat SDK and Hindsight",
tags: { sdk: "@vectorize-io/hindsight-chat", topic: "Recommendation" }
},
{
title: "CrewAI + Hindsight Memory",
href: "/cookbook/applications/crewai-memory",
description: "CrewAI agents with persistent long-term memory via Hindsight",
tags: { sdk: "Agents" }
},
{
title: "Deliveryman Demo",
href: "/cookbook/applications/deliveryman-demo",
@@ -31,7 +31,7 @@ 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=gpt-4o-mini \
-e HINDSIGHT_API_LLM_MODEL=o3-mini \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
```
@@ -25,7 +25,7 @@ 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=gpt-4o-mini \
-e HINDSIGHT_API_LLM_MODEL=o3-mini \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
```
@@ -35,7 +35,7 @@ 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=gpt-4o-mini \
-e HINDSIGHT_API_LLM_MODEL=o3-mini \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
```
+27
View File
@@ -8,6 +8,33 @@ This changelog highlights user-facing changes only. Internal maintenance, CI/CD,
For full release details, see [GitHub Releases](https://github.com/vectorize-io/hindsight/releases).
## [0.4.14](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.14)
**Features**
- Add Chat SDK integration to give chatbots persistent memory. ([`fed987f9`](https://github.com/vectorize-io/hindsight/commit/fed987f9))
- Allow configuring which MCP tools are exposed per memory bank, and expand the MCP tool set with additional tools and parameters. ([`3ffec650`](https://github.com/vectorize-io/hindsight/commit/3ffec650))
- Enable the bank configuration API by default. ([`4d030707`](https://github.com/vectorize-io/hindsight/commit/4d030707))
- Support filtering graph-based memory retrieval by tags. ([`0bb5ca4c`](https://github.com/vectorize-io/hindsight/commit/0bb5ca4c))
- Add batch observations consolidation to process multiple observations more efficiently. ([`0aa7c2b3`](https://github.com/vectorize-io/hindsight/commit/0aa7c2b3))
- Add OpenClaw options to toggle autoRecall and exclude specific providers. ([`3f9eb27c`](https://github.com/vectorize-io/hindsight/commit/3f9eb27c))
- - Add a ZeroEntropy reranker provider option. ([`17259675`](https://github.com/vectorize-io/hindsight/commit/17259675))
**Improvements**
- Increase customization options for reflect, retain, and consolidation behavior. ([`2a322732`](https://github.com/vectorize-io/hindsight/commit/2a322732))
- Include source document metadata in fact extraction results. ([`87219b73`](https://github.com/vectorize-io/hindsight/commit/87219b73))
**Bug Fixes**
- Raise a clear error when embedding dimensions exceed pgvector HNSW limits (instead of failing later at runtime). ([`8cd65b98`](https://github.com/vectorize-io/hindsight/commit/8cd65b98))
- Fix multi-tenant schema isolation issues in storage and the bank config API. ([`b180b3ad`](https://github.com/vectorize-io/hindsight/commit/b180b3ad))
- Ensure LiteLLM embedding calls use the correct float encoding format to prevent embedding failures. ([`58f2de70`](https://github.com/vectorize-io/hindsight/commit/58f2de70))
- Improve recall performance by reducing memory usage during retrieval. ([`9f0c031d`](https://github.com/vectorize-io/hindsight/commit/9f0c031d))
- Handle observation regeneration correctly when underlying memories are deleted. ([`ac9a94ad`](https://github.com/vectorize-io/hindsight/commit/ac9a94ad))
- Fix reflect retrieval to correctly populate dependencies and enforce full hierarchical retrieval. ([`8b1a4658`](https://github.com/vectorize-io/hindsight/commit/8b1a4658))
- Fix OpenClaw health checks by passing the auth token to the health endpoint. ([`40b02645`](https://github.com/vectorize-io/hindsight/commit/40b02645))
## [0.4.13](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.13)
**Features**