mirror of
https://github.com/vectorize-io/hindsight.git
synced 2026-09-14 19:31:49 +08:00
Chris Bartholomew
7e17a120e2
The startup banner, package descriptions, docs-site tagline and llms.txt still carried "Agent Memory That Works Like Human Memory". The project's one-liner is now "Agent Memory That Learns" — align every published copy so they don't keep drifting apart. Covered: the banner printed on API startup, the four package descriptions that surface on PyPI, the two bundle READMEs, the Docusaurus tagline, the llms.txt header, and the header the llms-full.txt generator emits. Adds tests/test_banner.py — there was no coverage of banner.py at all, and the tagline is the first thing a user sees. The gradient wraps every character in an ANSI escape, so the tests strip the escapes and assert on the text that actually reads, plus the gradient endpoints and the logo-above-tagline ordering. Confirmed they fail if the tagline regresses. Claude-Session: https://claude.ai/code/session_011mnzArjiCdBxa8dh1H47Fa
118 lines
4.0 KiB
Plaintext
118 lines
4.0 KiB
Plaintext
# Hindsight
|
|
|
|
> Agent Memory That Learns
|
|
|
|
Hindsight is an agent memory system that gives AI agents persistent, structured memory across sessions. It extracts facts, entities, and relationships from conversations and enables temporal reasoning, opinion formation, and multi-strategy retrieval.
|
|
|
|
## Links
|
|
|
|
- [Full Documentation (llms-full.txt)](https://hindsight.vectorize.io/llms-full.txt): Complete documentation for LLM consumption
|
|
- [Quick Start](https://hindsight.vectorize.io/developer/api/quickstart): Get started in 60 seconds
|
|
- [Python SDK](https://hindsight.vectorize.io/sdks/python): Python client library
|
|
- [TypeScript SDK](https://hindsight.vectorize.io/sdks/nodejs): Node.js/TypeScript client
|
|
- [API Reference](https://hindsight.vectorize.io/api-reference): REST API documentation
|
|
- [OpenAPI Spec](https://hindsight.vectorize.io/openapi.json): Machine-readable API specification
|
|
- [MCP Server](https://hindsight.vectorize.io/sdks/mcp): Model Context Protocol integration
|
|
- [GitHub](https://github.com/vectorize-io/hindsight): Source code and issues
|
|
|
|
## Core Operations
|
|
|
|
- **Retain**: Store memories (extracts facts, entities, relationships automatically)
|
|
- **Recall**: Retrieve memories (semantic, keyword, graph, temporal search)
|
|
- **Reflect**: Deep analysis to form opinions and insights
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
pip install hindsight-client
|
|
```
|
|
|
|
```python
|
|
from hindsight import HindsightClient
|
|
|
|
client = HindsightClient(base_url="http://localhost:8888")
|
|
|
|
# Store
|
|
client.retain(bank_id="my-agent", content="Alice works at Google as a software engineer")
|
|
|
|
# Query
|
|
results = client.recall(bank_id="my-agent", query="What does Alice do?")
|
|
|
|
# Reflect
|
|
response = client.reflect(bank_id="my-agent", query="Tell me about Alice")
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
### Memory Banks
|
|
Each bank is an isolated memory store. One bank per user/agent. Banks contain facts, entities, documents, and their relationships.
|
|
|
|
### Memory Types
|
|
- World facts: General knowledge
|
|
- Experience facts: Personal experiences
|
|
- Opinion facts: Beliefs with confidence scores
|
|
|
|
### Document ID for Evolving Conversations
|
|
Use `document_id` to group messages in a conversation. Retaining with the same `document_id` replaces the previous version (upsert), keeping memory consistent as conversations evolve.
|
|
|
|
```python
|
|
client.retain(
|
|
bank_id="user-123",
|
|
content=messages,
|
|
document_id="session_abc" # Same ID = replace old version
|
|
)
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
Base URL: `http://localhost:8888`
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/v1/default/banks/{bank_id}/memories` | Store memories |
|
|
| POST | `/v1/default/banks/{bank_id}/memories/recall` | Retrieve memories |
|
|
| POST | `/v1/default/banks/{bank_id}/reflect` | Analyze and form opinions |
|
|
| GET | `/v1/default/banks/{bank_id}/profile` | Get bank profile |
|
|
| PUT | `/v1/default/banks/{bank_id}/profile` | Update bank profile |
|
|
| GET | `/v1/default/banks` | List all banks |
|
|
| POST | `/v1/default/banks` | Create a bank |
|
|
|
|
## Architecture Patterns
|
|
|
|
### Per-User Memory
|
|
One bank per user. Simplest pattern for chatbots and assistants.
|
|
[Guide](https://hindsight.vectorize.io/cookbook/per-user-memory)
|
|
|
|
### Support Agent + Shared Knowledge
|
|
User bank + shared docs bank. Client orchestrates queries to both banks and merges results.
|
|
[Guide](https://hindsight.vectorize.io/cookbook/support-agent-with-shared-knowledge)
|
|
|
|
## Installation
|
|
|
|
### Docker (recommended)
|
|
```bash
|
|
docker run -p 8888:8888 -e HINDSIGHT_API_LLM_PROVIDER=openai -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY ghcr.io/vectorize-io/hindsight
|
|
```
|
|
|
|
### Python (embedded)
|
|
```bash
|
|
pip install hindsight-all
|
|
```
|
|
|
|
### Clients
|
|
```bash
|
|
pip install hindsight-client # Python
|
|
npm install @vectorize-io/hindsight-client # TypeScript
|
|
```
|
|
|
|
## MCP Integration
|
|
|
|
Hindsight provides a Model Context Protocol server for direct AI agent integration:
|
|
|
|
```bash
|
|
pip install hindsight-mcp-server
|
|
hindsight-mcp-server --api-url http://localhost:8888
|
|
```
|
|
|
|
Tools exposed: `retain`, `recall`, `reflect`, `list_banks`, `create_bank`
|