ee4510a762
* fix(deps): address critical and high severity security vulnerabilities Bump vulnerable dependencies to patched versions across the monorepo: Python (critical/high): - fastmcp >=2.14.0 → >=3.2.0 (SSRF, path traversal, OAuth confused deputy, command injection) - langchain-core >=1.2.11 → >=1.2.22 (path traversal in legacy load_prompt) Python (low): - cryptography >=46.0.5 → >=46.0.6 (incomplete DNS name constraint enforcement) - pygments: add >=2.20.0 pin (ReDoS via GUID regex) Node.js: - serialize-javascript ^7.0.3 → ^7.0.5 (CPU exhaustion DoS) - handlebars: add >=4.7.9 override (JS injection via AST type confusion) - path-to-regexp: add >=0.1.13 override (ReDoS via route params) - brace-expansion: add version range override (process hang/memory exhaustion) Also adds type: ignore comments for FastMCP 2.x private attribute access that ty now flags since FastMCP 3.x removed _tool_manager (guarded by try/except and hasattr at runtime). Regenerated all lock files across API, integrations, and tests. * fix(deps): add ajv v8 scoped overrides for schema-utils and ajv-keywords The global ajv ^6.14.0 override caused schema-utils and ajv-keywords to receive ajv v6, but they require ajv v8 (for dist/compile/codegen). Add scoped overrides to ensure these packages get ajv v8 while the global override remains for packages that need v6. * fix(tests): remove stateless_http from FastMCP() constructor calls FastMCP 3.x no longer accepts stateless_http in the constructor. The tests call tools directly without HTTP transport, so the parameter is not needed. * fix: update MCP tests for FastMCP 3.x _tool_manager removal FastMCP 3.x removed _tool_manager. Tests now use _local_provider._components for sync tool dict access and mcp.list_tools() for async filtered tool listing. * fix: resolve docusaurus build failures (ajv overrides + missing blog date) - Remove global ajv ^6.14.0 override and scoped ajv-keywords/schema-utils overrides that caused webpack compilation errors manifesting as "Cannot read properties of undefined (reading 'date')" during SSR and "these parameters are deprecated" warnings. Natural version resolution (v6.12.6+ for v6 consumers, v8+ for v8 consumers) already satisfies the security fix (>= 6.12.3). - Add missing date frontmatter to learning-capabilities blog post. * chore: regenerate openapi spec and docs skill |
||
|---|---|---|
| .. | ||
| hindsight_api | ||
| tests | ||
| pyproject.toml | ||
| README.md | ||
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 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
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
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 --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:
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
License
Apache 2.0