Hindsight API
Memory System for AI Agents — Temporal + Semantic + Entity Memory Architecture using PostgreSQL with pgvector.
Hindsight gives AI agents persistent memory that works like human memory: it stores facts, tracks entities and relationships, handles temporal reasoning ("what happened last spring?"), and forms opinions based on configurable disposition traits.
Installation
pip install hindsight-api
Quick Start
Run the Server
# Set your LLM provider
export HINDSIGHT_API_LLM_PROVIDER=openai
export HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx
# Start the server (uses embedded PostgreSQL by default)
hindsight-api
The server starts at http://localhost:8888 with:
- REST API for memory operations
- MCP server at
/mcpfor tool-use integration
Use the Python API
from hindsight_api.engine.memory_engine import MemoryEngine
from hindsight_api.models import RequestContext
# Create and initialize the memory engine
memory = MemoryEngine()
await memory.initialize()
ctx = RequestContext()
# Create a memory bank for your agent
# (optional: banks are also auto-created on first retain)
await memory.ensure_bank_profile("my-assistant", request_context=ctx)
await memory.set_bank_mission(
"my-assistant",
"A helpful coding assistant",
request_context=ctx,
)
# Store a memory
await memory.retain_async(
bank_id="my-assistant",
content="The user prefers Python for data science projects",
request_context=ctx,
)
# Recall memories
results = await memory.recall_async(
bank_id="my-assistant",
query="What programming language does the user prefer?",
request_context=ctx,
)
# Reflect with reasoning
answer = await memory.reflect_async(
bank_id="my-assistant",
query="Should I recommend Python or R for this ML project?",
request_context=ctx,
)
CLI Options
hindsight-api --help
# Common options
hindsight-api --port 9000 # Custom port (default: 8888)
hindsight-api --host 127.0.0.1 # Bind to localhost only
hindsight-api --workers 4 # Multiple worker processes
hindsight-api --log-level debug # Verbose logging
Configuration
Configure via environment variables:
| Variable | Description | Default |
|---|---|---|
HINDSIGHT_API_DATABASE_URL |
PostgreSQL connection string | pg0 (embedded) |
HINDSIGHT_API_LLM_PROVIDER |
LLM provider, including openai, anthropic, gemini, groq, ollama, lmstudio, and github-copilot |
openai |
HINDSIGHT_API_LLM_API_KEY |
API key for providers that require one; unused by github-copilot |
- |
HINDSIGHT_API_LLM_MODEL |
Model name | gpt-4o-mini |
HINDSIGHT_API_HOST |
Server bind address | 0.0.0.0 |
HINDSIGHT_API_PORT |
Server port | 8888 |
Example with External PostgreSQL
export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
hindsight-api
Docker
docker run -it --name hindsight --restart unless-stopped -p 8888:8888 \
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
MCP Server
For local MCP integration without running the full API server:
hindsight-local-mcp
This runs a stdio-based MCP server that can be used directly with MCP-compatible clients.
Key Features
- Multi-Strategy Retrieval (TEMPR) — Semantic, keyword, graph, and temporal search combined with RRF fusion
- Entity Graph — Automatic entity extraction and relationship tracking
- Temporal Reasoning — Native support for time-based queries
- Disposition Traits — Configurable skepticism, literalism, and empathy influence opinion formation
- Three Memory Types — World facts, experience facts (the bank's own actions), and observations
Documentation
Full documentation: https://hindsight.vectorize.io
License
- Apache 2.0
1 maintainer
Metadata
1 maintainer
Release files for hindsight-api 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| hindsight_api-1.1.0.tar.gz | 3.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hindsight_api-1.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 8.1 kB
Release files / hindsight_api-1.1.0.tar.gz
| Download URL | hindsight_api-1.1.0.tar.gz |
|---|---|
| Size | 3.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ee538dc4f06d22a64d82129f3962e1ee93797857151be60f72f17b3e4716a28
|
|
BLAKE2b-256 checksum How to use checksums |
8b23c27f70c87e9d96fa2a807ed90e1dc2bcbb29e4aada6d465266d287708c26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / hindsight_api-1.1.0-py3-none-any.whl
| Download URL | hindsight_api-1.1.0-py3-none-any.whl |
|---|---|
| Size | 4.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e9bc7964608f25c0aa24be4e596eefd33e96ad9427c81e79058b18e90dc08b46
|
|
BLAKE2b-256 checksum How to use checksums |
273c0753a836a571b7a509ae9a49cafe6a1c6910a2a406426eeb3b12f56ff3ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for hindsight-api 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for hindsight_api-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
