105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# Hindsight
|
|
|
|
[](https://github.com/vectorize-io/hindsight/actions/workflows/test.yml)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://pypi.org/project/hindsight-client/)
|
|
[](https://pypi.org/project/hindsight-api/)
|
|
[](https://pypi.org/project/hindsight-all/)
|
|
[](https://www.npmjs.com/package/@vectorize-io/hindsight-client)
|
|
|
|
**Long-term memory for AI agents.**
|
|
|
|
## Why Hindsight?
|
|
|
|
AI assistants forget everything between sessions. Every conversation starts from zero—no context about who you are, what you've discussed, or what the memory bank has learned. This isn't just inconvenient; it fundamentally limits what AI memory banks can do.
|
|
|
|
**The problem is harder than it looks:**
|
|
|
|
- **Simple vector search isn't enough** — "What did Alice do last spring?" requires temporal reasoning, not just semantic similarity
|
|
- **Facts get disconnected** — Knowing "Alice works at Google" and "Google is in Mountain View" should let you answer "Where does Alice work?" even if you never stored that directly
|
|
- **Memory banks need opinions** — A coding assistant that remembers "the user prefers functional programming" should weigh that when making recommendations
|
|
- **Context matters** — The same information means different things to different memory banks with different personalities
|
|
|
|
Hindsight solves these problems with a memory system designed specifically for AI memory banks.
|
|
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Docker (recommended)
|
|
|
|
Get the full experience with the API and Control Plane UI:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY=your-key
|
|
docker run -p 8888:8888 -p 9999:9999 \
|
|
-e HINDSIGHT_API_LLM_PROVIDER=openai \
|
|
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
|
|
-e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini \
|
|
ghcr.io/vectorize-io/hindsight
|
|
```
|
|
|
|
- **API**: http://localhost:8888
|
|
- **Control Plane UI**: http://localhost:9999
|
|
|
|
Then use the Python client:
|
|
|
|
```bash
|
|
pip install hindsight-client
|
|
```
|
|
|
|
```python
|
|
from hindsight import HindsightClient
|
|
|
|
client = HindsightClient(base_url="http://localhost:8888")
|
|
|
|
# Store memories
|
|
client.retain(bank_id="my-agent", content="Alice works at Google as a software engineer")
|
|
client.retain(bank_id="my-agent", content="Alice mentioned she loves hiking in the mountains")
|
|
|
|
# Query with temporal reasoning
|
|
results = client.recall(bank_id="my-agent", query="What does Alice do for work?")
|
|
|
|
# Get a synthesized perspective
|
|
response = client.reflect(bank_id="my-agent", query="Tell me about Alice")
|
|
print(response.text)
|
|
```
|
|
|
|
### Option 2: Embedded (no docker/server required)
|
|
|
|
For quick prototyping, run everything in-process:
|
|
|
|
```bash
|
|
pip install hindsight-all
|
|
export OPENAI_API_KEY=your-key
|
|
```
|
|
|
|
```python
|
|
import os
|
|
from hindsight import HindsightServer, HindsightClient
|
|
|
|
with HindsightServer(llm_provider="openai", llm_model="gpt-4o-mini", llm_api_key=os.environ["OPENAI_API_KEY"]) as server:
|
|
client = HindsightClient(base_url=server.url)
|
|
|
|
client.retain(bank_id="my-user", content="User prefers functional programming")
|
|
response = client.reflect(bank_id="my-user", query="What coding style should I use?")
|
|
print(response.text)
|
|
```
|
|
|
|
|
|
|
|
## Documentation
|
|
|
|
Full documentation: [vectorize-io.github.io/hindsight](https://vectorize-io.github.io/hindsight)
|
|
|
|
- [Architecture](https://vectorize-io.github.io/hindsight/#what-hindsight-does) — How ingestion, storage, and retrieval work
|
|
- [Python Client](https://vectorize-io.github.io/hindsight/sdks/python) — Full API reference
|
|
- [API Reference](https://vectorize-io.github.io/hindsight/api-reference) — REST API endpoints
|
|
- [Personality](https://vectorize-io.github.io/hindsight/developer/personality) — Big Five traits and opinion formation
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
|
|
|
|
## License
|
|
|
|
MIT
|