mirror of https://github.com/vectorize-io/hindsight.git synced 2026-09-14 19:31:49 +08:00

Files

T

Chris Bartholomew 7e17a120e2 chore: update the tagline to "Agent Memory That Learns" (#4093 )

The startup banner, package descriptions, docs-site tagline and llms.txt
still carried "Agent Memory That Works Like Human Memory". The project's
one-liner is now "Agent Memory That Learns" — align every published copy so
they don't keep drifting apart.

Covered: the banner printed on API startup, the four package descriptions
that surface on PyPI, the two bundle READMEs, the Docusaurus tagline, the
llms.txt header, and the header the llms-full.txt generator emits.

Adds tests/test_banner.py — there was no coverage of banner.py at all, and
the tagline is the first thing a user sees. The gradient wraps every
character in an ANSI escape, so the tests strip the escapes and assert on
the text that actually reads, plus the gradient endpoints and the
logo-above-tagline ordering. Confirmed they fail if the tagline regresses.

Claude-Session: https://claude.ai/code/session_011mnzArjiCdBxa8dh1H47Fa

2026-09-07 10:20:57 +02:00

pyproject.toml

chore: update the tagline to "Agent Memory That Learns" (#4093 )

2026-09-07 10:20:57 +02:00

README.md

feat(llm): add GitHub Copilot subscription provider (#3597 )

2026-08-19 15:48:00 +02:00

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 /mcp for 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`	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