Hindsight HTTP API (0.1.0)

Checks the health of the API and database connection

Exports metrics in Prometheus format for scraping

Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.

List memory units with pagination and optional full-text search. Supports filtering by type. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).

Recall memory using semantic similarity and spreading activation.

The type parameter is optional and must be one of:

• world: General knowledge about people, places, events, and things that happen
• experience: Memories about experience, conversations, actions taken, and tasks performed
• opinion: The bank's formed beliefs, perspectives, and viewpoints

Set include_entities=true to get entity observations alongside recall results.

Reflect and formulate an answer using bank identity, world facts, and opinions.

This endpoint:

1. Retrieves experience (conversations and events)
2. Retrieves world facts relevant to the query
3. Retrieves existing opinions (bank's perspectives)
4. Uses LLM to formulate a contextual answer
5. Extracts and stores any new opinions formed
6. Returns plain text answer, the facts used, and new opinions

Retain memory items with automatic fact extraction.

This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the async parameter.

Features:

• Efficient batch processing
• Automatic fact extraction from natural language
• Entity recognition and linking
• Document tracking with automatic upsert (when document_id is provided)
• Temporal and semantic linking
• Optional asynchronous processing

The system automatically:

1. Extracts semantic facts from the content
2. Generates embeddings
3. Deduplicates similar facts
4. Creates temporal, semantic, and entity links
5. Tracks document metadata

When async=true: Returns immediately after queuing. Use the operations endpoint to monitor progress.

When async=false (default): Waits for processing to complete.

Note: If a memory item has a document_id that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).

Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.

Get a list of all agents with their profiles

Get statistics about nodes and links for a specific agent

Get disposition traits and background for a memory bank. Auto-creates agent with defaults if not exists.

Update bank's disposition traits (skepticism, literalism, empathy)

Add new background information or merge with existing. LLM intelligently resolves conflicts, normalizes to first person, and optionally infers disposition traits.

Create a new agent or update existing agent with disposition and background. Auto-fills missing fields with defaults.

List all entities (people, organizations, etc.) known by the bank, ordered by mention count.

Get detailed information about an entity including observations (mental model).

Regenerate observations for an entity based on all facts mentioning it.

List documents with pagination and optional search. Documents are the source content from which memory units are extracted.

Get a specific document including its original text

Delete a document and all its associated memory units and links.

This will cascade delete:

• The document itself
• All memory units extracted from this document
• All links (temporal, semantic, entity) associated with those memory units

This operation cannot be undone.

Get a specific chunk by its ID

Get a list of all async operations (pending and failed) for a specific agent, including error messages for failed operations

Cancel a pending async operation by removing it from the queue