15ea23d5d6
* feat: introduce hindsight-api-slim and hindsight-all-slim packages Closes #552 - Move all source code from hindsight-api/ to new hindsight-api-slim/ - hindsight-api-slim has heavy ML deps (torch, sentence-transformers, transformers, einops, flashrank, mlx, mlx-lm, safetensors) and pg0-embedded as optional extras: [local-ml], [embedded-db], [all] - hindsight-api becomes a zero-code meta-package depending on hindsight-api-slim[all] for full backward compatibility - Add hindsight-all-slim meta-package: hindsight-api-slim + client + embed - hindsight-all updated to depend on hindsight-api-slim[all] - pg0.py: lazy-import pg0 with clear ImportError pointing to [embedded-db] - Dockerfile: replace sed hack with proper uv sync --extra flags - Update release.yml, test.yml, lint.sh, release.sh, CLAUDE.md and all path references throughout the repo * refactor: rename hindsight/ directory to hindsight-all/ * docs: document hindsight-api-slim and hindsight-all-slim package variants Add package variants table and extras explanation to installation.md * docs: remove emojis from installation.md, use professional tone * docs: link Docker slim variant to pip package variants section * docs: consolidate Docker image variants into single table * ci: fix working-directory paths after package restructure - Replace all hindsight-api → hindsight-api-slim in test.yml - Replace hindsight → hindsight-all in test.yml - Add --extra embedded-db to test-embed API install step * ci: add local-ml and embedded-db extras to API sync steps These extras were previously implicit in the old hindsight-api package (which bundled everything). Now that hindsight-api-slim uses optional extras, we must explicitly request local-ml and embedded-db in CI. * ci: add API install step with embedded-db to test-embed smoke test The smoke test starts hindsight-api as a daemon, which requires pg0-embedded. Add a dedicated install step for hindsight-api-slim with embedded-db extra so the daemon can start successfully. * ci: remove --no-install-project when using optional extras When --no-install-project is combined with --extra, the optional deps are not installed because extras require the project to be active. Remove --no-install-project from steps that need local-ml or embedded-db. * ci: fix ordering of uv sync steps to preserve optional extras When uv sync runs for a different workspace member, it removes optional extras installed for other members. Fix by always running extra-requiring API sync last, after other workspace member syncs. Also remove --no-install-project from embedded-db sync in test-embed, as --no-install-project prevents optional extras from being active. * ci: add local-ml extra to test-embed API install for smoke test The smoke test starts the full API server which needs sentence-transformers for local embeddings (default provider). Add local-ml extra to the install. * ci: simplify extras with --all-extras and add slim pip smoke test - Replace explicit --extra local-ml --extra embedded-db with --all-extras for cleaner, more maintainable sync steps - Add test-pip-slim job: tests hindsight-api-slim[embedded-db] without local ML models, using Cohere for embeddings/reranking (mirrors Docker slim smoke test approach) * ci: simplify slim smoke test to health check only (mirrors Docker test)
137 lines
3.9 KiB
Markdown
137 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pip install hindsight-api
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Run the Server
|
|
|
|
```bash
|
|
# 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 `/mcp` for tool-use integration
|
|
|
|
### Use the Python API
|
|
|
|
```python
|
|
from hindsight_api import MemoryEngine
|
|
|
|
# Create and initialize the memory engine
|
|
memory = MemoryEngine()
|
|
await memory.initialize()
|
|
|
|
# Create a memory bank for your agent
|
|
bank = await memory.create_memory_bank(
|
|
name="my-assistant",
|
|
background="A helpful coding assistant"
|
|
)
|
|
|
|
# Store a memory
|
|
await memory.retain(
|
|
memory_bank_id=bank.id,
|
|
content="The user prefers Python for data science projects"
|
|
)
|
|
|
|
# Recall memories
|
|
results = await memory.recall(
|
|
memory_bank_id=bank.id,
|
|
query="What programming language does the user prefer?"
|
|
)
|
|
|
|
# Reflect with reasoning
|
|
response = await memory.reflect(
|
|
memory_bank_id=bank.id,
|
|
query="Should I recommend Python or R for this ML project?"
|
|
)
|
|
```
|
|
|
|
## CLI Options
|
|
|
|
```bash
|
|
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` | `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio` | `openai` |
|
|
| `HINDSIGHT_API_LLM_API_KEY` | API key for LLM provider | - |
|
|
| `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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
docker run --rm -it -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:
|
|
|
|
```bash
|
|
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, bank actions, and formed opinions with confidence scores
|
|
|
|
## Documentation
|
|
|
|
Full documentation: [https://hindsight.vectorize.io](https://hindsight.vectorize.io)
|
|
|
|
- [Installation Guide](https://hindsight.vectorize.io/developer/installation)
|
|
- [Configuration Reference](https://hindsight.vectorize.io/developer/configuration)
|
|
- [API Reference](https://hindsight.vectorize.io/api-reference)
|
|
- [Python SDK](https://hindsight.vectorize.io/sdks/python)
|
|
|
|
## License
|
|
|
|
Apache 2.0
|