How vectorize-io/hindsight works
Hindsight is a long-term memory system for AI agents. Its principal workflow is to retain information in a bank, then recall relevant memories or reflect on them to produce a disposition-aware response. The repository also documents bank management, mental models, knowledge pages, MCP access, and webhook delivery. The graph reflects these product capabilities and the API/engine layers visible in the tree; some feature-level wiring is not shown because the corresponding route and engine source was not sampled.
Main entry points: memory_engine.py Memory engine · postgres.py Memory database · retrieval.py Recall retrieval · http.py HTTP API
Components 25
Access surfaces
- Client SDKs
hindsight-clients/go/client.go - Command-line client
hindsight-cli/src/main.rs
API and operations
- API server
hindsight-api-slim/hindsight_api/main.py - HTTP API
hindsight-api-slim/hindsight_api/api/http.py - Memory engine
hindsight-api-slim/hindsight_api/engine/memory_engine.py - Memory banks
hindsight-api-slim/hindsight_api/engine/bank_aliases.py - Operation worker
hindsight-api-slim/hindsight_api/worker/main.py - Operation tasks
hindsight-api-slim/hindsight_api/engine/task_backend.py
Memory lifecycle
- Retain orchestration
hindsight-api-slim/hindsight_api/engine/retain/orchestrator.py - Chunk storage
hindsight-api-slim/hindsight_api/engine/retain/chunk_storage.py - Fact storage
hindsight-api-slim/hindsight_api/engine/retain/fact_storage.py - Consolidation
hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py - Import and export
hindsight-api-slim/hindsight_api/engine/transfer/export.py - Memory database
hindsight-api-slim/hindsight_api/engine/memories/postgres.py
Retrieval and reasoning
- Recall retrieval
hindsight-api-slim/hindsight_api/engine/search/retrieval.py - Query analysis
hindsight-api-slim/hindsight_api/engine/query_analyzer.py - Reflect agent
hindsight-api-slim/hindsight_api/engine/reflect/agent.py - Mental models
hindsight-api-slim/hindsight_api/engine/mental_model_refresh.py - Knowledge pages
hindsight-api-slim/hindsight_api/api/page_markdown.py
Integrations
- MCP API
hindsight-api-slim/hindsight_api/api/mcp.py - LLM providers
hindsight-api-slim/hindsight_api/engine/providers/__init__.py - Webhook manager
hindsight-api-slim/hindsight_api/webhooks/manager.py
Other components
- Agent or user
- LLM service
- Webhook endpoint
Connections 29
- Agent or user → Client SDKs: uses
- Agent or user → Command-line client: uses
- Client SDKs → HTTP API: HTTP requests
- Command-line client → HTTP API: HTTP requests
- API server → HTTP API: mounts
- HTTP API → Memory engine: dispatches
- MCP API → Memory engine: dispatches
- Memory engine → Memory banks: manages
- Memory engine → Retain orchestration: retains
- Memory engine → Recall retrieval: recalls
- Memory engine → Reflect agent: reflects
- Retain orchestration → Chunk storage: stores chunks
- Retain orchestration → Fact storage: stores facts
- Fact storage → Memory database: writes facts
- Chunk storage → Memory database: writes chunks
- Consolidation → Memory database: updates memories
- Recall retrieval → Query analysis: analyzes query
- Recall retrieval → Memory database: retrieves memories
- Reflect agent → Recall retrieval: uses retrieval
- Reflect agent → LLM providers: requests generation
- LLM providers → LLM service: calls model
- Mental models → LLM providers: requests generation
- Knowledge pages → Memory engine: serves page APIs
- Import and export → Memory database: imports or exports
- Memory engine → Operation tasks: submits operations
- Operation worker → Operation tasks: processes tasks
- Webhook manager → Memory database: reads registrations
- Webhook manager → Operation tasks: queues delivery
- Webhook endpoint → Webhook manager: receives events