Hindsight Docs

Hindsight Documentation Skill

Complete technical documentation for Hindsight - a biomimetic memory system for AI agents.

When to Use This Skill

Use this skill when you need to:

• Understand Hindsight architecture and core concepts
• Learn about retain/recall/reflect operations
• Configure memory banks and dispositions
• Set up the Hindsight API server (Docker, Kubernetes, pip)
• Integrate with Python/Node.js/Rust SDKs
• Understand retrieval strategies (semantic, BM25, graph, temporal)
• Debug issues or optimize performance
• Review API endpoints and parameters
• Find cookbook examples and recipes

Documentation Structure

All documentation is in references/ organized by category:

references/
├── best-practices.md # START HERE — missions, tags, formats, anti-patterns
├── faq.md            # Common questions and decisions
├── changelog/        # Release history and version changes (index.md + integrations/)
├── openapi.json      # Full OpenAPI spec — endpoint schemas, request/response models
├── developer/
│   ├── api/          # Core operations: retain, recall, reflect, memory banks
│   └── *.md          # Architecture, configuration, deployment, performance
├── sdks/
│   ├── *.md          # Python, Node.js, CLI, embedded
│   └── integrations/ # LiteLLM, AI SDK, OpenClaw, MCP, skills
└── cookbook/
    ├── recipes/      # Usage patterns and examples
    └── applications/ # Full application demos

How to Find Documentation

1. Find Files by Pattern (use Glob tool)

# Core API operations
references/developer/api/*.md

# SDK documentation
references/sdks/*.md
references/sdks/integrations/*.md

# Cookbook examples
references/cookbook/recipes/*.md
references/cookbook/applications/*.md

# Find specific topics
references/**/configuration.md
references/**/*python*.md
references/**/*deployment*.md

2. Search Content (use Grep tool)

# Search for concepts
pattern: "disposition"        # Memory bank configuration
pattern: "graph retrieval"    # Graph-based search
pattern: "helm install"       # Kubernetes deployment
pattern: "document_id"        # Document management
pattern: "HINDSIGHT_API_"     # Environment variables

# Search in specific areas
path: references/developer/api/
pattern: "POST /v1"           # Find API endpoints

path: references/cookbook/
pattern: "def |async def "    # Find Python examples

3. Read Full Documentation (use Read tool)

references/developer/api/retain.md
references/sdks/python.md
references/cookbook/recipes/per-user-memory.md

Start Here: Best Practices

Before reading API docs, read the best practices guide. It covers practical rules for missions, tags, content format, observation scopes, and anti-patterns — the fastest way to integrate correctly.

references/best-practices.md

Key Concepts

• Memory Banks: Isolated memory stores (one per user/agent)
• Retain: Store memories (auto-extracts facts/entities/relationships)
• Recall: Retrieve memories (4 parallel strategies: semantic, BM25, graph, temporal)
• Reflect: Disposition-aware reasoning using memories
• document_id: Groups messages in a conversation (upsert on same ID)
• Dispositions: Skepticism, literalism, empathy traits (1-5) affecting reflect
• Mental Models: Consolidated knowledge synthesized from facts

Notes

• Code examples are inlined from working examples
• Configuration uses HINDSIGHT_API_* environment variables
• Database migrations run automatically on startup
• Multi-bank queries require client-side orchestration
• Use document_id for conversation evolution (same ID = upsert)

---

Auto-generated from hindsight-docs/docs/. Run ./scripts/generate-docs-skill.sh to update.

<PageHero title="Best Practices" subtitle="Practical guidance for agents and developers integrating Hindsight memory into production systems." />

Contents

• Core Concepts — Memory banks, taxonomy, memory types
• Bank Configuration — Missions, dispositions, entity labels
• Retaining Data — Content format, context, document_id, tags, observation scopes
• Recalling Memories — Budget, tag filtering, entity label filtering, include options, query_timestamp
• Reflecting — Recall vs reflect, response_schema, auditing
• Mental Models — When to create, tag strategy, refresh
• Anti-patterns

---

Core Concepts

Memory Banks

A memory bank is an isolated memory store — the unit of separation between users, agents, or contexts. All operations (retain, recall, reflect) target a single bank. Banks do not share data.

• One bank per user is the most common pattern for multi-user applications
• One bank per agent is common for agent-specific long-term memory
• A shared bank with tags can work for cross-user analysis (see Tags)

Banks are auto-created on first use. Configure them before ingesting data to steer behavior.

---

Taxonomy

---

Memory Types

Facts extracted during retain are classified into three types:

Use types filtering in recall to target specific memory types.

---

Bank Configuration

Configure a bank before first use to steer memory behavior for your domain. Misconfigured missions are the single biggest cause of low-quality memories.

Writing Effective Missions

All three missions accept plain language. Be specific about your domain — vague missions produce vague results.

retain_mission

Injected into the fact extraction prompt. Tells the LLM what to extract and what to ignore.

Tips:

• List the fact types you want (preferences, decisions, errors, commitments)
• List what to ignore — this is as important as what to include
• Match the mission to your actual data type (conversations vs documents vs tickets)

observations_mission

Steers what patterns are synthesized during consolidation. Runs after retain.

Identify evolving preferences, recurring patterns, behavioral shifts, and contradictions
with prior knowledge. Focus on durable patterns — not transient states. Highlight when
user behavior contradicts previous observations.

Tips:

• Emphasize "durable patterns" to avoid ephemeral observation noise
• Mention contradiction detection explicitly if you need historical tracking
• Match scope to how often you expect patterns to change

reflect_mission

Sets the agent persona and reasoning frame for reflect operations.

---

Disposition Traits

Dispositions affect reflect only (not recall). Scale 1–5.

Common profiles:

---

Entity Labels

Define a controlled vocabulary for classification. The LLM will extract and normalize values to your defined set.

{
  "entity_labels": [
    {
      "key": "tech_stack",
      "type": "multi-values",
      "values": [
        {"value": "python", "description": "Python programming language"},
        {"value": "typescript", "description": "TypeScript / Node.js"},
        {"value": "react", "description": "React frontend framework"}
      ]
    },
    {
      "key": "priority",
      "type": "value",
      "tag": true,
      "values": [
        {"value": "high", "description": "Urgent or blocking"},
        {"value": "low", "description": "Nice to have"}
      ]
    }
  ]
}

• `type: "value"` — single value per entity (last write wins)
• `type: "multi-values"` — accumulates multiple values
• `tag: true` — extracted label values are also added as tags (enables filtering by entity value)

Use entity labels when you need consistent classification — domain-specific terms, status values, priority levels, engagement types.

---

Retaining Data

Content Format

Pass the richest representation available. Never pre-summarize.

Conversation JSON (preferred):

[
  {"role": "user",      "content": "I'm using React for the frontend.", "timestamp": "2025-06-01T10:30:00Z"},
  {"role": "assistant", "content": "Got it. What state management are you using?"},
  {"role": "user",      "content": "Zustand. We moved away from Redux last quarter."}
]

Why not pre-summarize: The LLM extracts facts, entities, and relationships from structure. A summary like "user uses React and Zustand" loses the temporal reference ("last quarter"), the entity relationship (React↔frontend, Redux↔migration), and the causal context (moved away from).

---

The context Field

High-impact on extraction quality. Always set it. Describes the nature and source of the content.

# Good — specific, descriptive
context="Customer support ticket #12345 from user Alice about a billing discrepancy"
context="Developer's architecture review session for the payments service"
context="User's onboarding form: stated goals, current tools, and team size"
context="Weekly standup notes: blockers, progress, and upcoming tasks"

# Bad — generic, adds no signal
context="some data"
context="conversation"
# Omitted entirely — extraction uses no context

---

The document_id Field

Use for upsert behavior. Same document_id = delete previous version and reprocess.

Rules:

• Use stable, meaningful IDs (session ID, ticket ID, document UUID)
• Always use the same ID for a growing conversation — retain the full conversation with each new message
• Do NOT use random UUIDs per retain call — this creates duplicates

# Good — stable session ID
client.retain(bank_id="user-alice", items=[{
    "content": full_conversation,
    "document_id": f"session-{session_id}",
}])

# Bad — new random ID every call = duplicates
client.retain(bank_id="user-alice", items=[{
    "content": full_conversation,
    "document_id": str(uuid.uuid4()),  # ❌ creates a new document each time
}])

---

The timestamp Field

Set whenever you have temporal context. Enables temporal retrieval strategies.

• ISO 8601 format: "2025-06-01T10:32:00Z"
• For conversations: set to when the conversation started
• Omitting it disables temporal ranking entirely

---

Tags: Naming Conventions

Tags scope visibility. A memory tagged user:alice is only returned for recall/reflect calls that include user:alice in their tags filter (with strict matching).

Standard naming conventions:

Multi-tenant minimum: Every retain for user data must include at least user:<id>. Omitting it makes the memory globally visible.

# Multi-tenant retain — always tag with user ID
items=[{
    "content": conversation,
    "tags": ["user:alice", "session:s_abc", "topic:billing"],
    "document_id": f"session-{session_id}",
}]

---

Metadata Schema

Use for source tracking and downstream linking. Not filterable — use tags for filtering.

# Source tracking
metadata={"source": "slack", "channel": "#engineering", "thread_id": "T123456"}

# Ticket linking
metadata={"ticket_id": "JIRA-123", "priority": "high", "reporter": "alice"}

# Document provenance
metadata={"url": "https://...", "section": "pricing-faq", "version": "2025-Q1"}

Metadata is returned with every recalled memory — use it to link memories back to source systems for UI display, deep-linking, or audit trails.

---

Observation Scopes

Controls which tag combinations get their own observation pass.

Custom scope example (recommended for multi-tenant):

# Observations scoped to: user-level, team-level, and combined
observation_scopes=[
    ["user:alice"],
    ["team:engineering"],
    ["user:alice", "team:engineering"],
]

---

Sync vs Async

Do not retain and recall in the same turn — retain is a write operation and the extracted memories will not be available immediately.

---

Recalling Memories

Budget Selection

Default to mid. Use low for high-frequency agent loops. Reserve high for explicit "deep recall" user-triggered flows.

---

Tag Filtering Modes

Decision guide:

• Shared global knowledge + per-user: tags=["user:alice"], tags_match="any" — returns Alice's memories and untagged global memories
• Fully partitioned (no leakage): tags=["user:alice"], tags_match="any_strict" — Alice's memories only
• Multi-condition AND: tags=["user:alice", "topic:billing"], tags_match="all_strict" — only where both tags present

`tag_groups` for complex filters:

Tag groups use a tree structure with and/or/not compound nodes and {"tags": [...], "match": "..."} leaf nodes.

# Alice's billing memories OR shared billing memories (no user tag)
recall(
    query="...",
    tag_groups=[
        {"or": [
            {"tags": ["user:alice", "topic:billing"], "match": "all_strict"},
            {"and": [
                {"tags": ["topic:billing"], "match": "any_strict"},
                {"not": {"tags": ["user:alice"], "match": "any_strict"}},
            ]},
        ]}
    ]
)

---

include Options

---

types Filtering

---

Filtering by Memory Shape with Entity Labels

When a single bank contains semantically similar memories that serve different purposes (e.g., concise operating rules vs. detailed troubleshooting procedures), ranking alone cannot reliably distinguish them — two memories about "entrypoints" will score similarly regardless of whether one is a one-line rule and the other is a multi-step runbook.

Use entity labels with tag: true to classify facts at retain time and hard-filter at recall time.

1. Define a label group on the bank:

{
  "entity_labels": [
    {
      "key": "memory_type",
      "description": "The type of knowledge: 'rule' for concise operating rules and canonical guidance, 'procedure' for step-by-step technical instructions and troubleshooting notes",
      "type": "value",
      "optional": false,
      "tag": true,
      "values": [
        { "value": "rule",      "description": "Concise operating rule or canonical guidance" },
        { "value": "procedure", "description": "Step-by-step technical instruction or troubleshooting note" }
      ]
    }
  ]
}

2. Retain normally — the LLM classifies each fact automatically and writes memory_type:rule or memory_type:procedure as a tag.

3. Filter at recall time:

# Only rules — procedures are excluded at the database level, not post-filtered
result = client.recall(
    bank_id="my-bank",
    query="which entrypoint should I use?",
    tags=["memory_type:rule"],
    tags_match="any_strict"
)

This is a hard SQL WHERE clause applied across all four retrieval strategies. The unwanted memories never enter the ranking pipeline.

---

query_timestamp

Set for time-sensitive queries. Anchors temporal ranking to a specific point in time.

# "What was the team working on in January?"
recall(query="team priorities", query_timestamp="2025-01-31T23:59:59Z")

# Current context (most common)
recall(query="user preferences", query_timestamp=datetime.utcnow().isoformat() + "Z")

---

Reflecting

Recall vs Reflect

---

response_schema

Use when you need structured output for programmatic consumption.

reflect(
    query="What are the user's top 3 technical preferences?",
    response_schema={
        "type": "object",
        "properties": {
            "preferences": {
                "type": "array",
                "items": {"type": "string"},
                "maxItems": 3
            },
            "confidence": {"type": "number", "minimum": 0, "maximum": 1}
        },
        "required": ["preferences", "confidence"]
    }
)
# Returns: result.structured_output["preferences"], result.structured_output["confidence"]

---

Auditing and Debugging

Enable include.facts in production for audit trails. Enable include.tool_calls only during development.

---

Mental Models

Mental models are pre-computed reflect responses stored for common queries. They return instantly and consistently.

When to Create

• Common repeated queries that should return consistent answers
• High-traffic agents that need sub-100ms responses
• User profiles or personas read on every request
• Knowledge summaries reviewed or approved by humans
• Cross-session state that changes slowly (preferences, skills, background)

Tag Strategy

Tags on a mental model filter BOTH which memories are used to build it AND which recall/reflect calls can see it.

# Per-user mental model — uses Alice's memories (all_strict applied automatically during refresh)
create_mental_model(
    bank_id="shared-bank",
    name="Alice's Technical Profile",
    source_query="Summarize Alice's technical background, preferred stack, and current projects",
    tags=["user:alice"],
)

# Global mental model — uses all memories, visible to everyone
create_mental_model(
    bank_id="shared-bank",
    name="Team Engineering Standards",
    source_query="What are the team's agreed engineering standards and conventions?",
    # No tags — reads all memories, visible to all
)

Refresh Strategy

Create narrow, scoped models — one per knowledge dimension. A mental model titled "Everything about the user" is as useful as none.

Model granularity examples for a personal assistant:

• "User Profile" — demographics, preferences, stated goals
• "Current Projects" — active work, deadlines, blockers
• "Technical Stack" — languages, tools, frameworks used
• "Communication Style" — formality preferences, response length preferences

---

Anti-patterns

import PageHero from '@site/src/components/PageHero';

<PageHero title="Changelog" subtitle="User-facing changes only. Internal maintenance and infrastructure updates are omitted." />

0.5.0

Breaking Changes

• Removed BFS and MPFP graph retrieval strategies. LinkExpansionRetriever is now the sole graph retrieval algorithm, offering simpler, faster, and more accurate results. (`ea834bc7`)
• Dropped the hindsight-hermes integration package. (`cf0537ba`)

Features

• Built-in llama.cpp LLM provider for fully local inference without external API calls. (`f74b577e`)
• Retain update_mode='append' for concatenating new content onto an existing document instead of replacing it. (`3c633e5e`)
• OpenRouter support for LLM, embeddings, and reranking. (`e5944b63`)
• Bank template import/export with Template Hub — export a bank's configuration, mental models, and directives as a reusable manifest, then import into other banks. (`30a319a6`)
• Constellation view in the Control Plane — interactive, zoomable canvas visualization of entity relationship graphs with heat-gradient coloring and dark mode support. (`36783df3`)
• Added detail parameter to list/get mental model endpoints for controlling response verbosity. (`8d1bfbbd`)
• Added AutoGen integration (hindsight-autogen) for persistent long-term memory in AutoGen agents. (`a757765a`)
• Added Paperclip integration (@vectorize-io/hindsight-paperclip) with Express middleware and process adapter modes for stateless agent memory. (`81441ee9`)
• Added OpenCode persistent memory plugin for the OpenCode editor. (`e1c6220f`)
• OpenClaw JSONL-backed retain queue for external API resilience — buffers retain calls locally when the API is unreachable. (`087545cc`)
• OpenClaw now supports bankId for static bank configurations. (`0e81d1a2`)
• Added Google embeddings and reranker provider support. (`07de798c`)
• Added persistent volume support in Helm chart for local model cache. (`cefa7554`)
• MCP server now includes a sync_retain tool and validates UUID inputs. (`48185a4b`)
• Recall combined scoring now includes proof_count boost for better ranking. (`26794aab`)

Improvements

• 3-phase retain pipeline restructures memory ingestion into pre-resolve, insert, and post-link phases, dramatically improving throughput under concurrent load by removing slow reads from write transactions. (`914ba796`)
• Recall entity graph expansion now caps per-entity fanout and includes a timeout fallback, preventing slow queries on banks with high-fanout entities. (`57f15445`)
• Fact serialization in think-prompt now includes occurred_end and mentioned_at for richer temporal context. (`37348c85`)
• Consolidation observation quality improved with structured processing rules. (`6f173b10`)

Bug Fixes

• LiteLLM SDK embeddings encoding_format is now configurable instead of hardcoded. (`cece2c90`)
• Fixed out-of-range content_index crash in recall result mapping. (`9790d904`)
• Experience fact types are now preserved correctly during normalization. (`9cfdd464`)
• Clear memories endpoint no longer deletes the bank profile. (`26a64cc0`)
• Embedding daemon clears stale processes on the port before starting. (`7d6c570a`)
• Per-bank vector index migration now respects vector extension configuration. (`4fd7c5d1`)
• Timeline group sort uses numeric date comparison instead of locale string comparison. (`f3f2c6b0`)
• Resolved 25 test regressions from the streaming retain pipeline. (`7415ebff`)
• MCP server now auto-coerces string-encoded JSON in tool arguments. (`443c94c8`)
• Entity labels structure is now validated on PATCH to prevent invalid configurations. (`7e23f8e1`)
• Fixed bank_id metric label to be opt-in, preventing OTel memory leak. (`cf4bd598`)
• Fixed max_tokens handling for OpenAI-compatible endpoints with custom base URLs. (`cd99eef4`)
• Fixed event_date AttributeError when date is None in fact extraction. (`6cb309f7`)
• Query analyzer now handles dateparser internal crashes gracefully. (`e0e65c44`)
• Embedding profile .env overwrite skipped when config has no Hindsight keys. (`9e2890ba`)
• Windows compatibility fix for hindsight-embed. (`f9fe6953`)
• Addressed critical and high severity security vulnerabilities in dependencies. (`ee4510a7`)

0.4.22

Features

• API now supports passing custom LLM request parameters via the HINDSIGHT_API_LLM_EXTRA_BODY configuration. (`ecaa1ad1`)
• Document metadata is now exposed through the API and control plane. (`627ec5d5`)
• Added a /code-review skill for automated code quality checks against project standards. (`bdb33c58`)
• ZeroEntropy reranker now supports a configurable base URL. (`a915584e`)
• Codex can now retain structured tool calls from rollout files. (`3461398b`)

Improvements

• Embeddings via the LiteLLM SDK can now optionally specify output dimensions. (`f841bcb9`)
• API responses now include an X-Ignored-Params header to warn when unknown request parameters were ignored. (`cef42d81`)
• OpenClaw CLI startup is faster by deferring heavy initialization until the service starts. (`41025c3b`)

Bug Fixes

• Mental model triggers now support the full config schema, including tag matching and tag group filters. (`2c32ffad`)
• Cohere reranking via Azure endpoints now works reliably (avoids 404 errors). (`84985ee9`)
• Claude Code provider no longer defers to built-in tools, preventing MCP tool handling issues. (`fa82efc8`)
• Recall endpoint now returns metadata correctly instead of dropping it from the response. (`4768bf39`)
• Gemini 3.1+ tool calls now read thought signatures correctly. (`1b5c262a`)
• First-person agent memories are now correctly classified as "experience" facts. (`00961156`)
• Codex upgrades now preserve and merge new settings instead of skipping them. (`b104bad0`)
• LlamaIndex integration fixes improve document ID handling, memory API behavior, and ReAct tracing. (`d93dfea8`)

0.4.21

Features

• Added audit logging for feature usage tracking, including request duration in audit entries. (`083295dc`)
• Added Hindsight memory integration for the OpenAI Codex CLI. (`0b17a67c`)
• Added an MCP hook to filter tool visibility per user. (`f8285b7b`)
• Added a per-bank limit setting to cap the number of observations stored per scope. (`b32767ca`)
• Added native Windows support so Hindsight can run without Docker. (`c5700ff5`)
• Added a 'none' LLM provider to support chunk-only storage without LLM calls. (`9e5a066d`)
• Added a setup command/skill to register hooks more reliably. (`22ca6a8d`)
• Hermes now supports file-based configuration. (`0ff36548`)
• Added a LiteLLM-based provider to support Bedrock and many additional LLM providers. (`db70fdbe`)
• Added support for Strands Agents SDK integration with Hindsight memory tools. (`7fe773c0`)
• Added LlamaIndex integration. (`2d787c4f`)
• Added AG2 framework integration. (`73123870`)
• Added support for Ark and Volcano LLM providers. (`417fac61`)
• Retain now supports delta mode to skip LLM processing for unchanged chunks on upsert. (`fd88c0ef`)
• Claude Code integration can now retain full sessions with document upsert and configurable tags, and records tool calls as structured JSON. (`2d31b67d`)
• MCP retain tool now supports selecting a retain strategy via a parameter. (`4285e944`)

Improvements

• OpenClaw logging is now configurable and can emit structured output. (`d441ab81`)
• Made inclusion of source facts in search observations configurable. (`5095d5e3`)
• Integrations no longer use hardcoded default models, relying on configured defaults instead. (`58e68f3e`)

Bug Fixes

• Improved MCP server compatibility by handling Claude Code GET probes and allowing stateless HTTP mode to be configured. (`d8050387`)
• Per-bank vector index creation now respects the configured vector extension setting. (`6488c9bc`)
• Verbose retain extraction now correctly includes the retain mission context. (`d2965e64`)
• Codex integration no longer crashes on startup when the API quota is exhausted (HTTP 429). (`111e8c70`)
• OpenAI embeddings client now correctly parses query parameters included in base_url. (`a209ef1a`)
• Fixed tool_choice handling for Codex/Claude Code when forcing specific tool calls. (`585ac76f`)
• OpenClaw auto-recall now supports a configurable timeout to prevent hangs. (`cd4d449f`)
• Fixed control plane UI issues affecting recall and data viewing. (`6bb83f46`)
• Recall responses now include associated metadata. (`0bcbf849`)
• Python client update_bank_config() now exposes all configurable fields. (`7c18723f`)
• API OpenAPI schema now correctly includes Pydantic v2 ValidationError fields. (`939cb40a`)
• JSON-string tags are now coerced to lists for MemoryItem and MCP tools to prevent tagging errors. (`c5273f5f`)

0.4.20

Features

• Add a one-command setup CLI package for the NemoClaw integration. (`d284de28`)
• Add a LangGraph integration for using Hindsight memory within LangGraph agents. (`b4320254`)
• Add reflect filters to exclude specific fact types and mental model content during reflection. (`ea662d06`)
• Introduce independent versioning for integrations so they can be released separately from the core server. (`31f1c53c`)
• Add a Claude Code integration plugin. (`f4390bdc`)

Improvements

• Add a wall-clock timeout to reflect operations so they don’t run indefinitely. (`8ce06e3e`)
• Provide richer context when validating operations via the OperationValidator extension. (`2eb1019d`)
• Make the hindsight-api package runnable directly via uvx by adding script entry points. (`97f7a365`)
• Support passing query parameters during OpenAI-compatible client initialization for broader provider compatibility. (`20e17f28`)
• Upgrade the default MiniMax model from M2.5 to M2.7. (`1f1462a5`)

Bug Fixes

• Prevent context overflow during observation search by disabling source facts in results. (`8e2e2d5b`)
• Fix Claude Code integration session startup by pre-starting the daemon in the background. (`26944e25`)
• Fix Claude Code integration installation and configuration experience so setup is more reliable. (`35b2cbb6`)
• Fix a memory leak in entity resolution that could grow over time under load. (`e6333719`)
• Avoid crashes and retain failures when the Postgres pg_trgm extension is unavailable by handling detection/fallback correctly. (`365fa3ce`)
• Strip Markdown code fences from model outputs across all LLM providers for more consistent parsing. (`2f2db2a6`)
• Return a clear 400 error for empty recall queries and fix a SQL parameterization issue. (`5cdc714a`)
• Ensure file retain requests include authentication headers so uploads work in authenticated deployments. (`78aa7c53`)
• Fix MCP tool calls when MCP_AUTH_TOKEN and TENANT_API_KEY differ. (`8364b9c5`)
• Allow claude-agent-sdk to install correctly on Linux/Docker environments. (`3f31cbf5`)
• In LiteLLM mode, fall back to the last user message when no explicit hindsight query is provided. (`5e8952c5`)
• Fix non-atomic async operation creation to prevent inconsistent operation records. (`94cf89b5`)
• Prevent orphaned parent operations when a batch retain child fails unexpectedly. (`43942455`)
• Fix failures for non-ASCII entity names by ensuring entity IDs are set correctly. (`438ce98b`)
• Correctly store LLM facts labeled as "assistant" as "experience" in the database. (`446c75f3`)

0.4.19

Features

• TypeScript client now works in Deno environments. (`72c25c97`)
• Added Agno integration to use Hindsight as a memory toolkit. (`8c378b98`)
• Added Hermes Agent integration (hindsight-hermes) for persistent memory. (`ef90842f`)
• Expanded retain behavior with new verbatim and chunks extraction modes and named retain strategies. (`e4f8a157`)

Improvements

• Improved local reranker performance/efficiency with FP16 and bucketed batching, plus compatibility with Transformers 5.x. (`e7da7d0e`)

Bug Fixes

• Prevented silent memory loss when consolidation fails (failed consolidations are tracked and can be recovered). (`28dac7c7`)
• Fixed Docker control-plane startup to respect the configured control-plane hostname. (`8a64dc8d`)
• Database cleanup migration now removes orphaned observation memory units to avoid inconsistent memory state. (`f09ad9de`)
• Deleting a document now also deletes linked memory units to prevent leftover/stale memory entries. (`f27bd953`)
• Fixed MCP middleware to send an Accept header, preventing 406 response errors in some setups. (`836fd81e`)
• Improved compatibility with Gemini tool-calling by preserving thought signature metadata to avoid failures on gemini-3.1-flash-lite-preview. (`21f9f46c`)

0.4.18

Features

• Add compound tag filtering using tag groups. (`5de793ee`)
• Publish new slim Python packages (hindsight-api-slim and hindsight-all-slim) for smaller installs. (`15ea23d5`)
• Add MiniMax as a supported LLM provider. (`2344484f`)
• Add Jina MLX reranker provider optimized for Apple Silicon. (`1caf5ec9`)

Improvements

• Allow configuring maximum recall query tokens via an environment variable. (`66dedb8d`)
• Improve retrieval performance by switching to per-bank HNSW indexes. (`43b3efc4`)

Bug Fixes

• Prevent reranking failures by truncating long documents that exceed LiteLLM reranker context limits. (`eeb938fc`)
• Ensure recalled memories are injected as system context for OpenClaw. (`b17f338e`)
• Ensure embedded profiles are registered in CLI metadata when the daemon starts. (`06b0f74a`)
• Cancel in-flight async operations when a bank is deleted to avoid dangling work. (`0560f626`)

0.4.17

Features

• Added a manual retry option for failed asynchronous operations. (`dcaacbe4`)
• You can now change/update tags on an existing document. (`1b4ad7f4`)
• Added history tracking and a diff view for mental model changes. (`e2baca8b`)
• Added observation history tracking with a UI diff view to review changes over time. (`576473b6`)
• File uploads can now choose a parser per request, with configurable fallback chains. (`99220d05`)
• Added an extension hook that runs after file-to-Markdown conversion completes. (`1d17dea2`)

Improvements

• Operations view now supports filtering by operation type and has more reliable auto-refresh behavior. (`f7a60f89`)
• Added token limits for “source facts” used during consolidation and recall to better control context usage. (`5d05962d`)
• Improved bank selector usability by truncating very long bank names in the dropdown. (`1e40cd22`)

Bug Fixes

• Fixed webhook schema issues affecting multi-tenant retain webhooks. (`32a4882a`)
• Fixed file ingestion failures by stripping null bytes from parsed file content before retaining. (`cd3a6a22`)
• Fixed tool selection handling for OpenAI-compatible providers when using named tool_choice. (`1cdfb7c2`)
• Improved consolidation behavior to prioritize a bank’s mission over an ephemeral-state heuristic. (`00ccf0b2`)
• Fixed database migrations to correctly handle mental model embedding dimension changes. (`7accac94`)
• Fixed file upload failures caused by an Iris parser httpx read timeout. (`fa3501d4`)
• Improved reliability of running migrations by serializing Alembic upgrades within the process. (`f88b50a4`)
• Fixed Google Cloud Storage authentication when using Workload Identity Federation credentials. (`d2504ac5`)
• Fixed the bank selector to refresh the bank list when the dropdown is opened. (`0ad8c2d0`)

0.4.16

Features

• Added Webhooks with consolidation.completed and retain.completed events. (`abbf874d`)

Improvements

• Improved OpenClaw recall/retention controls. (`d425e93c`)
• Improved search/reranking quality by switching combined scoring to multiplicative boosts. (`aa8e5475`)
• Improved performance of observation recall by 40x on large banks. (`ad2cf72a`)
• Improved server shutdown behavior by capping graceful shutdown time and allowing a forced kill on a second Ctrl+C. (`4c058b4b`)

Bug Fixes

• Fixed an async deadlock risk by running database schema migrations in a background thread during startup. (`e0a2ac63`)
• Fixed webhook delivery/outbox processing so transactions don’t silently roll back due to using the wrong database schema name. (`75b95106`)
• Fixed observation results to correctly resolve and return related chunks using source_memory_ids. (`cb6d1c46`)
• Fixed MCP bank-level tool filtering compatibility with FastMCP 3.x. (`f17406fd`)
• Fixed crashes when an LLM returns invalid JSON across all retries (now handled cleanly instead of raising a TypeError). (`66423b85`)
• Fixed observations without source dates to preserve missing (None) temporal fields instead of incorrectly populating them. (`891c33b1`)

0.4.15

Features

• Added observation_scopes to control the granularity/visibility of observations. (`55af4681`)
• List documents API now supports filtering by tags (and fixes the q parameter description). (`1d70abfe`)
• Added PydanticAI integration for persistent agent memory. (`cab5a40f`)
• Added richer entity label support (optional labels, free-form values, multi-value fields, and UI polish). (`9b96becc`)
• Added support for timestamp="unset" so content can be retained without a date. (`f903948a`)
• OpenClaw can now automatically retain the last n+2 turns every n turns (default n=10). (`ad1660b3`)
• Added configurable Gemini/Vertex AI safety settings for LLM calls. (`73ef99e7`)
• Added extension hooks to customize root routing and error headers. (`e407f4bc`)

Improvements

• Improved recall performance by fetching all recall chunks in a single query. (`61bf428b`)
• Improved recall/retain performance and scalability for large memory banks. (`7942f181`)

Bug Fixes

• Fixed the TypeScript SDK to send null (not undefined) when includeEntities is false. (`15f4b876`)
• Prevented reflect from failing with context_length_exceeded on large memory banks. (`77defd96`)
• Fixed a consolidation deadlock caused by retrying after zombie processing tasks. (`c2876490`)
• Fixed observations count in the control plane that always showed 0. (`eaeaa1f2`)
• Fixed ZeroEntropy rerank endpoint URL and ensured the MCP retain async_processing parameter is handled correctly. (`f6f1a7d8`)
• Fixed JSON serialization issues and logging-related exception propagation when using the claude_code LLM provider. (`ecb833f4`)
• Added bank-scoped request validation to prevent cross-bank/invalid bank operations. (`5270aa5a`)

0.4.14

Features

• Add Chat SDK integration to give chatbots persistent memory. (`fed987f9`)
• Allow configuring which MCP tools are exposed per memory bank, and expand the MCP tool set with additional tools and parameters. (`3ffec650`)
• Enable the bank configuration API by default. (`4d030707`)
• Support filtering graph-based memory retrieval by tags. (`0bb5ca4c`)
• Add batch observations consolidation to process multiple observations more efficiently. (`0aa7c2b3`)
• Add OpenClaw options to toggle autoRecall and exclude specific providers. (`3f9eb27c`)
• Add a ZeroEntropy reranker provider option. (`17259675`)

Improvements

• Increase customization options for reflect, retain, and consolidation behavior. (`2a322732`)
• Include source document metadata in fact extraction results. (`87219b73`)

Bug Fixes

• Raise a clear error when embedding dimensions exceed pgvector HNSW limits (instead of failing later at runtime). (`8cd65b98`)
• Fix multi-tenant schema isolation issues in storage and the bank config API. (`b180b3ad`)
• Ensure LiteLLM embedding calls use the correct float encoding format to prevent embedding failures. (`58f2de70`)
• Improve recall performance by reducing memory usage during retrieval. (`9f0c031d`)
• Handle observation regeneration correctly when underlying memories are deleted. (`ac9a94ad`)
• Fix reflect retrieval to correctly populate dependencies and enforce full hierarchical retrieval. (`8b1a4658`)
• Fix OpenClaw health checks by passing the auth token to the health endpoint. (`40b02645`)

0.4.13

Features

• Switched the default OpenAI LLM to gpt-4o-mini. (`325b5cc1`)
• Observation recall now includes the source facts behind recalled observations. (`5569d4ad`)
• Added CrewAI integration to enable persistent memory. (`41db2960`)

Bug Fixes

• Fixed npx hindsight-control-plane failing to run. (`0758827d`)
• Improved MCP compatibility by aligning the local MCP implementation with the server and removing the deprecated stateless parameter. (`ea8163c5`)
• Fixed Docker startup failures when using named Docker volumes. (`ac739487`)
• Prevented reranker crashes when an upstream provider returns an error. (`58c4d657`)
• Improved accuracy of fact temporal ordering by reducing per-fact time offsets. (`c3ef1555`)
• Client timeout settings are now properly respected. (`dcaa9f14`)
• Fixed documents not being tracked when fact extraction returns zero facts. (`f78278ea`)

0.4.12

Features

• Accept and ingest PDFs, images, and common Office documents as inputs. (`224b7b74`)
• Add the Iris file parser for improved document parsing support. (`7eafba66`)
• Add async Retain support via provider Batch APIs (e.g., OpenAI and Groq) for higher-throughput ingestion. (`40d42c58`)
• Allow Recall to return chunks only (no memories) by setting max_tokens=0. (`7dad9da0`)
• Add a Go client SDK for the Hindsight API. (`2a47389f`)
• Add support for the pgvectorscale (DiskANN) vector index backend. (`95c42204`)
• Add support for Azure pg_diskann vector indexing. (`476726c2`)

Improvements

• Improve reliability of async batch Retain when ingesting large payloads. (`aefb3fcf`)
• Improve AI SDK tooling to make it easier to work with Hindsight programmatically. (`d06a0259`)

Bug Fixes

• Ensure document tags are preserved when using the async Retain flow. (`b4b5c44a`)
• Fix OpenClaw ingestion failures for very large content (E2BIG). (`6bad6673`)
• Harden OpenClaw behavior (safer shell usage, better HTTP mode handling, and more reliable initialization), including per-user banks support. (`c4610130`)
• Improve Python client async API consistency and reduce connection drop issues via keepalive timeout fixes. (`8114ef44`)

0.4.11

Features

• Added support for LiteLLM SDK as an embeddings and reranking provider. (`e408b7e`)
• Expanded Postgres search support with additional text/vector extensions, including TimescaleDB pg_textsearch and vchord/pgvector options. (`d871c30`)
• Added hierarchical configuration scopes (system, tenant, bank) for more flexible multi-tenant setup and overrides. (`8d731f2`)
• Added reverse proxy/base-path support for running Hindsight behind a proxy. (`93ddd41`)
• Added MCP tools to create, read, update, and delete mental models. (`f641b30`)
• Added a "docs" skill for agents/tools to access documentation-oriented capabilities. (`dd1e098`)
• Added an OpenClaw configuration option to skip recall/retain for specific providers. (`fb7be3e`)

Improvements

• Improved LiteLLM gateway model configuration for more reliable provider/model selection. (`7d95a00`)
• Exposed actual LLM token usage in retain results to improve cost/usage visibility. (`83ca669`)
• Added user-initiated attribution to request context to improve async task and usage attribution. (`90be7c6`)
• Added OpenTelemetry tracing for improved request traceability and observability. (`69dec8e`)
• Helm chart: split TEI embedding and reranker into separate deployments for independent scaling and rollout. (`43f9a8b`)
• Helm chart: added PodDisruptionBudgets and per-component affinity controls for more resilient scheduling. (`9943957`)

Bug Fixes

• Fixed a recursion issue in memory retention that could cause failures or runaway memory usage. (`4f11210`)
• Fixed Reflect API serialization/schema issues for "based_on" so reflections are returned and stored correctly. (`f9a8a8e`)
• Improved MCP server compatibility by allowing extra tool arguments when appropriate and fixing bank ID resolution priority. (`7ee229b`)
• Added missing trust_code environment configuration support. (`60574ee`)
• Hardened the MCP server with fixes to routing/validation and more accurate usage metering. (`e798979`)
• Fixed the slim Docker image to include tiktoken to prevent runtime tokenization errors. (`6eec83b`)
• Fixed MCP operations not being tracked correctly for usage metering. (`888b50d`)
• Helm chart: fixed GKE deployments overriding the configured HINDSIGHT_API_PORT. (`03f47e2`)

0.4.10

Features

• Provided a slimmer Docker distribution to reduce image size and speed up pulls. (`f648178`)
• Added Markdown support in Reflect and Mental Models content. (`c4ef090`)
• Added built-in Supabase tenant extension for running Hindsight with Supabase-backed multi-tenancy. (`e99ee0f`)
• Added TenantExtension authentication support to the MCP endpoint. (`fedfb49`)

Improvements

• Improved MCP tool availability/routing based on the endpoint being used. (`d90588b`)

Bug Fixes

• Stopped logging database usernames and passwords to prevent credential leaks in logs. (`c568094`)
• Fixed OpenClaw sessions wiping memory on each new session. (`981cf60`)
• Fixed hindsight-embed profiles not loading correctly. (`0430588`)
• Fixed tagged directives so they correctly apply to tagged mental models. (`278718d`)
• Fixed a cast error that could cause failures at runtime. (`093ecff`)

Other

• Added a docker-compose example to simplify local deployment and testing. (`5179d5f`)

0.4.9

Features

• New AI SDK integration. (`7e339e1`)
• Add a Python SDK for running Hindsight in embedded mode (HindsightEmbedded). (`d3302c9`)
• Add streaming support to the hindsight-litellm wrappers. (`665877b`)
• Add OpenClaw support for connecting to an external Hindsight API and using dynamic per-channel memory banks. (`6b34692`)

Improvements

• Improve the mental models experience in the control plane UI. (`7097716`)
• Reduce noisy Hugging Face logging output. (`34d9188`)

Bug Fixes

• Improve recall endpoint reliability by handling timeouts correctly and rejecting overly long queries. (`dd621a6`)
• Improve /reflect behavior with Claude Code and Codex providers. (`a43d208`)
• Fix OpenClaw shell argument escaping for more reliable command execution. (`63e2964`)

0.4.8

Features

• Added profile support for hindsight-embed, enabling separate embedding configurations/workspaces. (`6c7f057`)
• Added support for additional LLM backends, including OpenAI Codex and Claude Code. (`539190b`)

Improvements

• Enhanced OpenClaw and hindsight-embed parameter/config options for easier configuration and better defaults. (`749478d`)
• Added OpenClaw plugin configuration options to select LLM provider and model. (`8564135`)
• Server now prints its version during startup to simplify debugging and support requests. (`1499ce5`)
• Improved tracing/debuggability by propagating request context through asynchronous background tasks. (`44d9125`)
• Added stronger validation and context for mental model create/refresh operations to prevent invalid requests. (`35127d5`)

Bug Fixes

• Improved embedding CLI experience with richer logs and isolated profiles to avoid cross-contamination between runs. (`794a743`)
• Operation validation now runs correctly in the worker process, preventing invalid background operations from slipping through. (`96f0e54`)
• Fixed unreliable behavior when using a custom PostgreSQL schema. (`3825506`)

0.4.7

Features

• Add extension hooks to validate and customize mental model operations. (`9c3fda7`)
• Add support for using an external embedding API provider in OpenClaw plugin (with additional OpenClaw compatibility fixes). (`4b57b82`)

Improvements

• Speed up container startup by preloading the tiktoken encoding during Docker image builds. (`039944c`)

Bug Fixes

• Prevent PostgreSQL insert failures by stripping null bytes from text fields before saving. (`ef9d3a1`)
• Fix worker schema selection so it uses the correct default database schema. (`d788a55`)
• Honor an already-set HINDSIGHT_API_DATABASE_URL instead of overwriting it in the hindsight-embed workflow. (`f0cb192`)

0.4.6

Improvements

• Improved OpenClaw configuration setup to make embedding integration easier to configure. (`27498f9`)

Bug Fixes

• Fixed OpenClaw embedding version binding/versioning to prevent mismatches when using the embed integration. (`1163b1f`)

0.4.5

Bug Fixes

• Fixed occasional failures when retaining memories asynchronously with timestamps. (`cbb8fc6`)

0.4.4

Bug Fixes

• Fixed async “retain” operations failing when a timestamp is provided. (`35f0984`)
• Corrected the OpenClaw daemon integration name to “openclaw” (previously “openclawd”). (`b364bc3`)

0.4.3

Features

• Add Vertex AI as a supported LLM provider. (`c2ac7d0`, `49ae55a`)
• Add Bearer token authentication for MCP and propagate tenant authentication across MCP requests. (`0da77ce`)

Improvements

• CLI: add a --wait flag for consolidate and a --date filter for listing documents. (`ff20bf9`)

Bug Fixes

• Fix worker polling deadlocks to prevent background processing from stalling. (`f4f86e3`)
• Improve reliability of Docker builds by retrying ML model downloads. (`ecc590c`)
• Fix tenant authentication handling for internal background tasks and ensure the control-plane forwards required auth to the dataplane. (`03bf13e`)
• Ensure tenant database migrations run at startup and workers use the correct tenant schema context. (`657fe02`)
• Fix control-plane graph endpoint errors when upstream data is missing. (`751f99a`)

Other

• Rename the default bot/user identity from "moltbot" to "openclaw". (`728ce13`)

0.4.2

Features

• Added Clawdbot/Moltbot/OpenClaw integration. (`12e9a3d`)

Improvements

• Added additional configuration options to control LLM retry behavior. (`3f211f0`)
• Added real-time logs showing a detailed timing breakdown during consolidation runs. (`8781c9f`)

Bug Fixes

• Fixed hindsight-embed crashing on macOS. (`c16ccc2`)

0.4.1

Features

• Added support for using a non-default PostgreSQL schema by default. (`2b72e1f`)

Improvements

• Improved memory consolidation performance (benchmarking and optimizations). (`b43ef98`)

Bug Fixes

• Fixed the /version endpoint returning an incorrect version. (`cfcc23c`)
• Fixed mental model search failing due to UUID type mismatch after text-ID migration. (`94cc0a1`)
• Added safer PyTorch device detection to prevent crashes on some environments. (`67c4788`)
• Fixed Python packages exposing an incorrect __version__ value. (`fccbdfe`)

0.4.0

Observations, Mental Models, new Agentic Reflect and Directives, read the announcement.

Features

• Added support for providing a custom prompt for memory extraction. (`3172e99`)
• Expanded the LiteLLM integration with async retain/reflect support, cleaner API, and support for tags/mission (including passing API keys correctly). (`1d4879a`)
• Added a new worker service to run background tasks at scale. (`4c79240`)
• MCP retain now supports timestamps. (`b378f68`)
• Added support for installing skills via npx add-skill. (`ec22317`)

Improvements

• CLI retain-files now accepts more file types. (`1eeced3`)

Bug Fixes

• Fixed a macOS crash in the embed daemon caused by an XPC connection issue. (`e5fc6ee`)
• Fixed occasional extraction in the wrong language. (`87d4a36`)
• Fixed PyTorch model initialization issues that could cause startup failures (meta tensor/init problems). (`ddaa5f5`)

Features

• Add memory tags so you can label and filter memories during recall/reflect. (`20c8f8b`)
• Allow choosing different AI providers/models per operation. (`e6709d5`)
• Add Cohere support for embeddings and reranking. (`4de0730`)
• Add configurable embedding dimensions and OpenAI embeddings support. (`70de23e`)
• Support custom base URLs for OpenAI-style embeddings and Cohere endpoints. (`fa53917`)
• Add LiteLLM gateway support for routing LLM/embedding requests. (`d47c8a2`)
• Add multilingual content support to improve handling and retrieval across languages. (`c65c6a9`)
• Add delete memory bank capability. (`4b82d2d`)
• Add backup/restore tooling for memory banks. (`67b273d`)

Improvements

• Add retention modes to control how memories are extracted and stored. (`fb31a35`)
• Add offline (optional) database migrations to support restricted/air-gapped deployments. (`233bd2e`)
• Add database connection configuration options for more flexible deployments. (`33fac2c`)
• Load .env automatically on startup to simplify configuration. (`c06d9b4`)
• Expose an operation ID from retain requests so async/background processing can be tracked. (`1dacd0e`)
• Add per-request LLM token usage metrics for monitoring and cost tracking. (`29a542d`)
• Add LLM call latency metrics for performance monitoring. (`5e1f13e`)
• Include tenant in metrics labels for better multi-tenant observability. (`1ffc2a4`)
• Add async processing option to MCP retain tool for background retention workflows. (`37fc7fb`)

Bug Fixes

• Fix extension loading in multi-worker deployments so all workers load extensions correctly. (`f5f3fca`)
• Improve recall performance by batching recall queries. (`5991308`)
• Improve retrieval quality and stability for large memory banks (graph/MPFP retrieval fixes). (`6232e69`)
• Fix entities list being limited to 100 entities. (`26bf571`)
• Fix UI only showing the first 1000 memories. (`67c1a42`)
• Fix duplicated causal relationships and improve token usage during processing. (`49e233c`)
• Improve causal link detection accuracy. (`2a00df0`)
• Make retain max completion tokens configurable to prevent truncation issues. (`7715a51`)
• Fix Python SDK not sending the Authorization header, preventing authenticated requests. (`39e3f7c`)
• Fix stats endpoint missing tenant authentication in multi-tenant setups. (`d6ff191`)
• Fix embedding dimension handling for tenant schemas in multi-tenant databases. (`6fe9314`)
• Fix Groq free-tier compatibility so requests work correctly. (`d899d18`)
• Fix security vulnerability (qs / CVE-2025-15284). (`b3becb6`)
• Restore MCP tools for listing and creating memory banks. (`9fd5679`)

0.2.0

Features

• Add additional model provider support, including Anthropic Claude and LM Studio. (`787ed60`)
• Add multi-bank access and new MCP tools for interacting with multiple memory banks via MCP. (`6b5f593`)
• Allow supplying custom entities when retaining memories via the retain endpoint. (`dd59bc8`)
• Enhance the /reflect endpoint with max_tokens control and optional structured output responses. (`d49e820`)

Improvements

• Improve local LLM support for reasoning-capable models and streamline Docker startup for local deployments. (`eea0f27`)
• Support operation validator extensions and return proper HTTP errors when validation fails. (`ce45d30`)
• Add configurable observation thresholds to control when observations are created/updated. (`54e2df0`)
• Improve graph visualization to the control plane for exploring memory relationships. (`1a62069`)

Bug Fixes

• Fix MCP server lifecycle handling so MCP lifespan is correctly tied to the FastAPI app lifespan. (`6b78f7d`)

0.1.15

Features

• Add the ability to delete documents from the web UI. (`f7ff32d`)

Improvements

• Improve the API health check endpoint and update the generated client APIs/types accordingly. (`e06a612`)

0.1.14

Bug Fixes

• Fixes the embedded “get-skill” installer so installing skills works correctly. (`0b352d1`)

0.1.13

Improvements

• Improve reliability by surfacing task handler failures so retries can occur when processing fails. (`904ea4d`)
• Revamp the hindsight-embed component architecture, including a new daemon/client model and CLI updates for embedding workflows. (`e6511e7`)

Bug Fixes

• Fix memory retention so timestamps are correctly taken into account. (`234d426`)

0.1.12

Features

• Added an extensions system for plugging in new operations/skills (including built-in tenant support). (`2a0c490`)
• Introduced the hindsight-embed tool and a native agentic skill for embedding/agent workflows. (`da44a5e`)

Improvements

• Improved reliability when parsing LLM JSON by retrying on parse errors and adding clearer diagnostics. (`a831a7b`)

Bug Fixes

• Fixed structured-output support for Ollama-based LLM providers. (`32bca12`)
• Adjusted LLM validation to cap max completion tokens at 100 to prevent validation failures. (`b94b5cf`)

0.1.11

Bug Fixes

• Fixed the standalone Docker image and control plane standalone build process so standalone deployments build correctly. (`2948cb6`)

0.1.10

This release contains internal maintenance and infrastructure changes only.

0.1.9

Features

• Simplified local MCP installation and added a standalone UI option for easier setup. (`1c6acc3`)

Bug Fixes

• Fixed the standalone Docker image so it builds and starts reliably. (`b52eb90`)
• Improved Docker runtime reliability by adding required system utilities (procps). (`ae80876`)

0.1.8

Bug Fixes

• Fix bank list responses when a bank has no name. (`04f01ab`)
• Fix failures when retaining memories asynchronously. (`63f5138`)
• Fix a race condition in the bank selector when switching banks. (`e468a4e`)

0.1.7

This release contains internal maintenance and infrastructure changes only.

0.1.6

Features

• Added support for the Gemini 3 Pro and GPT-5.2 models. (`bb1f9cb`)
• Added a local MCP server option for running/connecting to Hindsight via MCP without a separate remote service. (`7dd6853`)

Improvements

• Updated the Postgres/pg0 dependency to a newer 0.11.x series for improved compatibility and stability. (`47be07f`)

0.1.5

Features

• Added LiteLLM integration so Hindsight can capture and manage memories from LiteLLM-based LLM calls. (`dfccbf2`)
• Added an optional graph-based retriever (MPFP) to improve recall by leveraging relationships between memories. (`7445cef`)

Improvements

• Switched the embedded Postgres layer to pg0-embedded for a smoother local/standalone experience. (`94c2b85`)

Bug Fixes

• Fixed repeated retries on 400 errors from the LLM, preventing unnecessary request loops and failures. (`70983f5`)
• Fixed recall trace visualization in the control plane so search/recall debugging displays correctly. (`922164e`)
• Fixed the CLI installer to make installation more reliable. (`158a6aa`)
• Updated Next.js to patch security vulnerabilities (CVE-2025-55184, CVE-2025-55183). (`f018cc5`)

0.1.3

Improvements

• Improved CLI and UI branding/polish, including new banner/logo assets and updated interface styling. (`fa554b8`)

0.1.2

Bug Fixes

• Fixed the standalone Docker image so it builds/runs correctly. (`1056a20`)

Integration Changelogs

ag2 Integration Changelog

Changelog for `hindsight-ag2`.

For the source code, see `hindsight-integrations/ag2`.

← Back to main changelog

0.1.1

Features

• Added AG2 framework integration for Hindsight. (`73123870`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="Vercel AI SDK Changelog" subtitle="@vectorize-io/hindsight-ai-sdk — memory integration for Vercel AI SDK." />

← Vercel AI SDK integration

AutoGen Integration Changelog

Changelog for `hindsight-autogen`.

For the source code, see `hindsight-integrations/autogen`.

← Back to main changelog

0.1.1

Features

• Added AutoGen integration to connect Hindsight with AutoGen-based agent workflows. (`a757765a`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="Vercel Chat SDK Changelog" subtitle="@vectorize-io/hindsight-chat — memory integration for Vercel Chat SDK." />

← Vercel Chat SDK integration

import PageHero from '@site/src/components/PageHero';

<PageHero title="Claude Code Changelog" subtitle="hindsight-memory — Hindsight memory plugin for Claude Code." />

← Claude Code integration

0.3.0

Features

• Claude Code integration now retains tool calls as structured JSON for more accurate memory and retrieval. (`8cb8b912`)

0.2.0

Features

• Added a Claude Code integration plugin for capturing and using Hindsight memory in Claude Code. (`f4390bdc`)
• Claude Code integration can retain full sessions with document upsert and configurable tagging. (`2d31b67d`)

Improvements

• Improved Claude Code plugin installation and configuration experience. (`35b2cbb6`)
• Integrations no longer rely on hardcoded default models, allowing model selection to be fully configured. (`58e68f3e`)
• Claude Code now starts the Hindsight background daemon automatically at session start for smoother operation. (`26944e25`)

Bug Fixes

• Added a supported setup command to register hooks reliably, fixing hook registration issues. (`22ca6a8d`)
• Fixed Claude Code integration compatibility on Windows. (`a94a90ea`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="OpenAI Codex CLI Changelog" subtitle="Hindsight memory integration for OpenAI Codex CLI." />

← Codex CLI integration

0.2.0

Features

• Retain structured Codex tool calls from rollout files so they’re preserved in Hindsight memory. (`3461398b`)

0.1.1

Features

• Added Hindsight memory integration for the OpenAI Codex CLI, enabling Codex to use and store memories in Hindsight. (`0b17a67c`)

0.1.0

Features

• Added Hindsight memory integration for OpenAI Codex CLI with three hook scripts: SessionStart (daemon warm-up), UserPromptSubmit (auto-recall), and Stop (auto-retain). (`0b17a67c`)
• Full-session retain with session-level upsert using session ID as document ID. (`0b17a67c`)
• Dynamic bank IDs for per-project memory isolation. (`0b17a67c`)
• Automatic daemon lifecycle management with background pre-start. (`0b17a67c`)
• 57 automated tests covering content processing and end-to-end hook behavior. (`71125cd9`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="CrewAI Changelog" subtitle="hindsight-crewai — persistent memory for CrewAI agents." />

← CrewAI integration

import PageHero from '@site/src/components/PageHero';

<PageHero title="LangGraph Changelog" subtitle="hindsight-langgraph — LangGraph and LangChain memory integration." />

← LangGraph integration

0.1.1

Features

• Added LangGraph integration for Hindsight. (`b4320254`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="LiteLLM Changelog" subtitle="hindsight-litellm — universal LLM memory integration via LiteLLM." />

← LiteLLM integration

0.5.0

Features

• Add streaming support when using the LiteLLM wrapper integration. (`665877bb`)
• Add async retain and reflect support, along with a cleaned-up LiteLLM integration API. (`1d4879a2`)
• Initial release of the Hindsight LiteLLM integration implementation. (`dfccbf29`)

Improvements

• Support sending tags and mission metadata through the LiteLLM integration to improve memory organization and retrieval. (`f3c5a9c1`)

Bug Fixes

• When no explicit Hindsight query is provided, the integration now uses the most recent user message as the query to avoid missing/empty memory lookups. (`5e8952c5`)
• Fix API key handling by passing the configured api_key through to the Hindsight client in the LiteLLM integration. (`c0ca9b02`)

LlamaIndex Integration Changelog

Changelog for `hindsight-llamaindex`.

For the source code, see `hindsight-integrations/llamaindex`.

← Back to main changelog

0.1.3

Bug Fixes

• Fixed LlamaIndex integration issues with document IDs, the memory API, and ReAct trace handling to improve reliability and correctness. (`d93dfea8`)

0.1.2

Features

• Added LlamaIndex integration for Hindsight. (`2d787c4f`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="NemoClaw Changelog" subtitle="@vectorize-io/hindsight-nemoclaw — persistent memory for NemoClaw sandboxed agents." />

← NemoClaw integration

0.1.1

Features

• Added a setup CLI package for the Hindsight nemoclaw integration. (`d284de28`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="OpenClaw Changelog" subtitle="@vectorize-io/hindsight-openclaw — Hindsight memory plugin for OpenClaw." />

← OpenClaw integration

0.6.0 (Unreleased)

Breaking Changes

• The plugin no longer reads any configuration from process environment variables. All settings — including the LLM provider, model, API key, base URL, external Hindsight API URL/token, and bank ID — must now be set through OpenClaw's plugin config (e.g. openclaw config set plugins.entries.hindsight-openclaw.config.<field> <value>). API keys and other secrets should be configured as SecretRef values via --ref-source env|file|exec so they're resolved from your secret store at runtime instead of being stored in plaintext on disk.
• Removed the llmApiKeyEnv plugin config field. Use the new llmApiKey field configured as a SecretRef instead (e.g. openclaw config set plugins.entries.hindsight-openclaw.config.llmApiKey --ref-source env --ref-id OPENAI_API_KEY).
• Removed automatic LLM provider detection from OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / GROQ_API_KEY. Set llmProvider and llmApiKey explicitly via openclaw config set.
• Removed support for the HINDSIGHT_API_LLM_PROVIDER, HINDSIGHT_API_LLM_MODEL, HINDSIGHT_API_LLM_API_KEY, HINDSIGHT_API_LLM_BASE_URL, HINDSIGHT_EMBED_API_URL, HINDSIGHT_EMBED_API_TOKEN, and HINDSIGHT_BANK_ID environment variables. The same values now live in plugin config — see the migration guide.

Features

• Added the llmApiKey plugin config field, marked as a sensitive field so OpenClaw resolves it as a SecretRef from env, file, or exec sources.
• Added the llmBaseUrl plugin config field for OpenAI-compatible endpoint overrides (OpenRouter, Azure OpenAI, vLLM, etc.).
• Marked hindsightApiToken as a sensitive field — it can now be configured as a SecretRef the same way as llmApiKey.

0.5.1

Bug Fixes

• Fixed JSON manifest formatting issues in the OpenClaw plugin to prevent manifest parsing/loading problems. (`704e41fa`)

0.5.0

Breaking Changes

• Removed hardcoded default model settings from integrations so model/provider must be configured explicitly. (`58e68f3e`)

Features

• Added configurable, structured logging for the OpenClaw integration. (`d441ab81`)
• Added an auto-recall toggle and support for excluding specific providers from recall/retention. (`3f9eb27c`)
• Added configuration to skip recall/retention for selected providers. (`fb7be3ec`)
• Added dynamic per-channel memory banks to isolate memory across channels. (`9a776e9f`)
• Added support for using an external Hindsight API backend. (`6b346925`)
• Added plugin configuration options to select the LLM provider and model. (`8564135b`)

Improvements

• Added control over where recalled memories are injected to better preserve prompt caching. (`200bab23`)
• Improved recall/retention controls and scalability, and added Gemini safety settings support. (`d425e93c`)
• Memory retention now periodically keeps recent conversation turns (default every 10 turns) to improve continuity. (`ad1660b3`)
• Improved OpenClaw and embedding parameters for better integration behavior and configuration. (`749478d9`)
• Improved OpenClaw configuration setup and initialization behavior. (`27498f99`)

Bug Fixes

• Added a configurable auto-recall timeout to prevent recalls from hanging or taking too long. (`cd4d449f`)
• Recalled memories are now injected as system context for more reliable behavior. (`b17f338e`)
• Health check requests now include the auth token to avoid unauthorized failures. (`40b02645`)
• Improved stability and safety with better shell handling, HTTP mode support, lazy reinitialization, and per-user memory banks. (`c4610130`)
• Fixed failures when ingesting very large content (E2BIG). (`6bad6673`)
• Prevented memory retention from recursing indefinitely. (`4f112101`)
• Prevented user memories from being wiped on every new session. (`981cf605`)
• Improved shell argument escaping to prevent command failures with special characters. (`63e2964a`)
• Renamed the OpenClaw binary to the correct name to avoid invocation/config mismatches. (`b364bc34`)

Paperclip Integration Changelog

Changelog for `@vectorize-io/hindsight-paperclip`.

For the source code, see `hindsight-integrations/paperclip`.

← Back to main changelog

0.1.1

Features

• Added the Hindsight Paperclip TypeScript integration. (`81441ee9`)

Bug Fixes

• Fixed issues in the Paperclip integration based on review feedback. (`7863ffeb`)

import PageHero from '@site/src/components/PageHero';

<PageHero title="Pydantic AI Changelog" subtitle="hindsight-pydantic-ai — persistent memory tools for Pydantic AI agents." />

← Pydantic AI integration

Strands Integration Changelog

Changelog for `hindsight-strands`.

For the source code, see `hindsight-integrations/strands`.

← Back to main changelog

0.1.1

Features

• Added Strands Agents SDK integration, enabling Hindsight memory tools to be used with Strands agents. (`7fe773c0`)

Admin CLI

The hindsight-admin CLI provides administrative commands for managing your Hindsight deployment, including database migrations, backup, and restore operations.

Installation

The admin CLI is included with the hindsight-api package:

pip install hindsight-api
# or
uv add hindsight-api

Commands

run-db-migration

Run database migrations to the latest version. By default this migrates the base schema plus all tenant schemas discovered by the tenant extension. Use --schema for targeted migration of one schema. This is useful when you want to run migrations separately from API startup (e.g., in CI/CD pipelines or before deploying a new version).

hindsight-admin run-db-migration [OPTIONS]

Options:

Examples:

# Run migrations on the base schema plus all discovered tenant schemas
hindsight-admin run-db-migration

# Run migrations on a specific tenant schema
hindsight-admin run-db-migration --schema tenant_acme

:::tip Disabling Auto-Migrations To disable automatic migrations on API startup, set HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP=false. This is useful when you want to run migrations as a separate step in your deployment pipeline. :::

---

backup

Create a backup of all Hindsight data to a zip file.

hindsight-admin backup OUTPUT [OPTIONS]

Arguments:

Options:

Examples:

# Backup to a file
hindsight-admin backup /backups/hindsight-2024-01-15.zip

# Backup a specific tenant schema
hindsight-admin backup /backups/tenant-acme.zip --schema tenant_acme

The backup includes:

• Memory banks and their configuration
• Documents and chunks
• Entities and their relationships
• Memory units (facts, experiences, observations)
• Entity cooccurrences and memory links

:::note Consistency Backups are created within a database transaction with REPEATABLE READ isolation, ensuring a consistent snapshot across all tables. :::

---

restore

Restore data from a backup file. Warning: This deletes all existing data in the target schema.

hindsight-admin restore INPUT [OPTIONS]

Arguments:

Options:

Examples:

# Restore with confirmation prompt
hindsight-admin restore /backups/hindsight-2024-01-15.zip

# Restore without confirmation (for scripts)
hindsight-admin restore /backups/hindsight-2024-01-15.zip --yes

# Restore to a specific tenant schema
hindsight-admin restore /backups/tenant-acme.zip --schema tenant_acme --yes

:::warning Data Loss Restore will delete all existing data in the target schema before importing the backup. Always verify you have a recent backup before performing a restore. :::

---

decommission-worker

Release all tasks owned by a worker, resetting them from "processing" back to "pending" status so they can be picked up by other workers.

hindsight-admin decommission-worker WORKER_ID [OPTIONS]

Arguments:

Options:

Examples:

# Before scaling down - release tasks from workers being removed
hindsight-admin decommission-worker hindsight-worker-4
hindsight-admin decommission-worker hindsight-worker-3

# Release tasks from a crashed worker
hindsight-admin decommission-worker worker-2

# For a specific tenant schema
hindsight-admin decommission-worker worker-1 --schema tenant_acme

When to Use:

• Scaling down: Before removing worker replicas in Kubernetes
• Graceful removal: When taking a worker offline for maintenance
• Crash recovery: If a worker crashed while processing tasks
• Stuck worker: When a worker is unresponsive

:::tip Finding Worker IDs Worker IDs default to the hostname. In Kubernetes StatefulSets, this is the pod name (e.g., hindsight-worker-0). You can also set a custom ID with HINDSIGHT_API_WORKER_ID or --worker-id. :::

---

Environment Variables

The admin CLI uses the same environment variables as the API service. The most important one is:

Example:

# Use a specific database
export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight
hindsight-admin backup /backups/mybackup.zip

Bank Templates

Declarative JSON manifests for creating pre-configured memory banks with a single API call.

{/ Import raw source files /}

Overview

A bank template is a JSON manifest that describes a bank's full setup: configuration overrides, mental models, directives, and more. Instead of making multiple API calls to configure a bank, you submit one manifest and the API provisions everything.

Templates are useful for:

• Replication — stamp out identically-configured banks for multiple users or agents
• Onboarding — new users start with a known-good configuration instead of configuring from scratch
• Sharing — distribute recommended setups as portable JSON files
• Framework integrations — ship a recommended template alongside your integration

Browse the Bank Templates Hub for ready-to-use templates.

Manifest Schema

{
  "version": "1",
  "bank": {
    "reflect_mission": "...",
    "retain_mission": "...",
    "retain_extraction_mode": "concise | verbose | custom | chunks",
    "retain_custom_instructions": "...",
    "retain_chunk_size": 2048,
    "disposition_skepticism": 3,
    "disposition_literalism": 3,
    "disposition_empathy": 3,
    "enable_observations": true,
    "observations_mission": "...",
    "entity_labels": ["PERSON", "ORGANIZATION"],
    "entities_allow_free_form": true
  },
  "mental_models": [
    {
      "id": "unique-lowercase-id",
      "name": "Human-Readable Name",
      "source_query": "The query that generates this mental model's content",
      "tags": ["optional", "tags"],
      "max_tokens": 2048,
      "trigger": {
        "refresh_after_consolidation": false,
        "fact_types": ["world", "experience", "observation"],
        "exclude_mental_models": false,
        "exclude_mental_model_ids": []
      }
    }
  ],
  "directives": [
    {
      "name": "directive-name",
      "content": "The directive instruction text",
      "priority": 0,
      "is_active": true,
      "tags": ["optional", "tags"]
    }
  ]
}

Fields

All of bank, mental_models, and directives are optional. Omit any section to leave that part of the bank unchanged.

Bank Config Fields

All fields in bank are optional. Only the fields you include will be set as per-bank overrides — everything else inherits from the server/tenant defaults.

Mental Model Fields

Directive Fields

Import

Import a manifest into a bank. If the bank doesn't exist, it's created automatically.

Python

template = {
    "version": "1",
    "bank": {
        "retain_mission": "Extract customer issues, resolutions, and sentiment.",
        "enable_observations": True,
        "observations_mission": "Track recurring customer pain points.",
    },
    "mental_models": [
        {
            "id": "sentiment-overview",
            "name": "Customer Sentiment Overview",
            "source_query": "What is the overall sentiment trend?",
            "trigger": {"refresh_after_consolidation": True},
        }
    ],
    "directives": [
        {
            "name": "Acknowledge frustration",
            "content": "Always acknowledge frustration before offering solutions.",
            "priority": 10,
        }
    ],
}

response = requests.post(
    f"{HINDSIGHT_URL}/v1/default/banks/my-bank/import",
    json=template,
)
result = response.json()
print(f"Config applied: {result['config_applied']}")
print(f"Mental models created: {result['mental_models_created']}")
print(f"Directives created: {result['directives_created']}")

Node.js

const template = {
  version: '1',
  bank: {
    retain_mission: 'Extract customer issues, resolutions, and sentiment.',
    enable_observations: true,
    observations_mission: 'Track recurring customer pain points.',
  },
  mental_models: [
    {
      id: 'sentiment-overview',
      name: 'Customer Sentiment Overview',
      source_query: 'What is the overall sentiment trend?',
      trigger: { refresh_after_consolidation: true },
    },
  ],
  directives: [
    {
      name: 'Acknowledge frustration',
      content: 'Always acknowledge frustration before offering solutions.',
      priority: 10,
    },
  ],
};

const importResponse = await fetch(
  `${HINDSIGHT_URL}/v1/default/banks/my-bank/import`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(template),
  },
);
const result = await importResponse.json();
console.log('Config applied:', result.config_applied);
console.log('Mental models created:', result.mental_models_created);
console.log('Directives created:', result.directives_created);

CLI

curl -X POST "$HINDSIGHT_URL/v1/default/banks/my-bank/import" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1",
    "bank": {
      "retain_mission": "Extract customer issues, resolutions, and sentiment.",
      "enable_observations": true,
      "observations_mission": "Track recurring customer pain points."
    },
    "mental_models": [
      {
        "id": "sentiment-overview",
        "name": "Customer Sentiment Overview",
        "source_query": "What is the overall sentiment trend?",
        "trigger": { "refresh_after_consolidation": true }
      }
    ],
    "directives": [
      {
        "name": "Acknowledge frustration",
        "content": "Always acknowledge frustration before offering solutions.",
        "priority": 10
      }
    ]
  }'

Go

# Section 'import-template' not found in api/bank-templates.go

Behavior

• Config: all bank fields are applied as per-bank config overrides
• Mental models: matched by id — existing models are updated, new ones are created
• Directives: matched by name — existing directives are updated, new ones are created
• Async: mental model content is generated asynchronously. The response includes operation_ids to track progress.

Dry Run

Validate a manifest without applying changes:

Python

response = requests.post(
    f"{HINDSIGHT_URL}/v1/default/banks/my-bank/import",
    params={"dry_run": "true"},
    json=template,
)
result = response.json()
print(f"Dry run: {result['dry_run']}")
print(f"Would apply config: {result['config_applied']}")

Node.js

const dryRunResponse = await fetch(
  `${HINDSIGHT_URL}/v1/default/banks/my-bank/import?dry_run=true`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(template),
  },
);
const dryRunResult = await dryRunResponse.json();
console.log('Dry run:', dryRunResult.dry_run);
console.log('Would apply config:', dryRunResult.config_applied);

CLI

curl -X POST "$HINDSIGHT_URL/v1/default/banks/my-bank/import?dry_run=true" \
  -H "Content-Type: application/json" \
  -d '{"version": "1", "bank": {"retain_mission": "Dry run test."}}'

Go

# Section 'import-dry-run' not found in api/bank-templates.go

Returns what would happen (which config would be applied, which mental models would be created) without making any changes. Returns HTTP 400 with a detailed error message if the manifest is invalid.

Export

Export a bank's current config overrides, mental models, and directives as a manifest:

Python

response = requests.get(
    f"{HINDSIGHT_URL}/v1/default/banks/my-bank/export"
)
exported = response.json()
print(json.dumps(exported, indent=2))

Node.js

const exportResponse = await fetch(
  `${HINDSIGHT_URL}/v1/default/banks/my-bank/export`,
);
const exported = await exportResponse.json();
console.log(JSON.stringify(exported, null, 2));

CLI

curl "$HINDSIGHT_URL/v1/default/banks/my-bank/export"

Go

# Section 'export-template' not found in api/bank-templates.go

The exported manifest only includes config fields that were explicitly set as per-bank overrides — not the fully resolved config (which includes server/tenant defaults). This means the exported manifest is portable: importing it into a new bank only overrides the fields that were intentionally customized.

Round-trip

Export from one bank and import into another to replicate the setup:

Python

# Export from source bank
response = requests.get(
    f"{HINDSIGHT_URL}/v1/default/banks/source-bank/export"
)
exported = response.json()

# Import into a new bank
response = requests.post(
    f"{HINDSIGHT_URL}/v1/default/banks/new-bank/import",
    json=exported,
)

Node.js

// Export from source bank
const srcResponse = await fetch(
  `${HINDSIGHT_URL}/v1/default/banks/source-bank/export`,
);
const srcExported = await srcResponse.json();

// Import into a new bank
await fetch(`${HINDSIGHT_URL}/v1/default/banks/new-bank/import`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(srcExported),
});

CLI

# Export from source bank
curl "$HINDSIGHT_URL/v1/default/banks/source-bank/export" > template.json

# Import into a new bank
curl -X POST "$HINDSIGHT_URL/v1/default/banks/new-bank/import" \
  -H "Content-Type: application/json" \
  -d @template.json

Go

# Section 'export-reimport' not found in api/bank-templates.go

JSON Schema

The manifest format is defined by a JSON Schema. Fetch the live schema from your server:

Python

response = requests.get(
    f"{HINDSIGHT_URL}/v1/bank-template-schema"
)
schema = response.json()
print(json.dumps(schema, indent=2))

Node.js

const schemaResponse = await fetch(
  `${HINDSIGHT_URL}/v1/bank-template-schema`,
);
const schema = await schemaResponse.json();
console.log(JSON.stringify(schema, null, 2));

CLI

curl "$HINDSIGHT_URL/v1/bank-template-schema"

Go

# Section 'get-schema' not found in api/bank-templates.go

The static schema is also available at bank-template-schema.json.

Control Plane

The control plane bank creation dialog includes an optional "Import from template" toggle. Enable it to paste a manifest JSON and pre-configure the bank on creation.

You can also export any bank's template from the bank Settings page via Actions → Export Template, which copies the manifest JSON to your clipboard.

Versioning

The version field enables forward-compatible schema evolution. The current version is "1".

When future versions are released:

• Older manifests are automatically upgraded to the current schema on import
• Export always produces the latest version
• The API rejects manifests with a version newer than what the server supports (with a clear error message suggesting an upgrade)

This means old templates keep working indefinitely — no need to manually update them.

Operations

Background tasks that Hindsight executes asynchronously.

:::tip Prerequisites Make sure you've completed the Quick Start and understand how retain works. :::

How Operations Work

Hindsight processes several types of tasks in the background to maintain memory quality and consistency. These operations run automatically—you don't need to trigger them manually.

By default, all background operations are executed in-process within the API service.

:::note Kafka Integration Support for external streaming platforms like Kafka for scale-out processing is planned but not available out of the box in the current release. :::

Operation Types

Async Retain Example

When retaining large batches of memories, use async=true to process in the background. The response includes an operation_id that you can use to poll for completion.

1. Submit async retain request

curl -X POST "http://localhost:8000/v1/default/banks/my-bank/memories" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"content": "Alice joined Google in 2023"},
      {"content": "Bob prefers Python over JavaScript"}
    ],
    "async": true
  }'

Response:

{
  "success": true,
  "bank_id": "my-bank",
  "items_count": 2,
  "async": true,
  "operation_id": "550e8400-e29b-41d4-a716-446655440000"
}

2. Poll for operation status

curl "http://localhost:8000/v1/default/banks/my-bank/operations"

Response:

{
  "bank_id": "my-bank",
  "operations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "task_type": "retain",
      "items_count": 2,
      "document_id": null,
      "created_at": "2024-01-15T10:30:00Z",
      "status": "completed",
      "error_message": null
    }
  ]
}

Operation Status Values

Managing Operations

Cancel a pending operation

curl -X DELETE "http://localhost:8000/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000"

Retry a failed operation

If an operation fails, you can manually re-queue it for execution:

curl -X POST "http://localhost:8000/v1/default/banks/my-bank/operations/550e8400-e29b-41d4-a716-446655440000/retry"

Response:

{
  "success": true,
  "message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
  "operation_id": "550e8400-e29b-41d4-a716-446655440000"
}

The operation status resets to pending and the worker picks it up again. Returns 409 if the operation is not in failed state.

Next Steps

• **Documents** — Track document sources
• **Memory Banks** — Configure bank settings

Go Client

Official Go client for the Hindsight API, generated from the OpenAPI 3.1 spec using OpenAPI Generator.

import CodeSnippet from '@site/src/components/CodeSnippet'; import quickstartGo from '!!raw-loader!@site/examples/api/quickstart.go';

Installation

go get github.com/vectorize-io/hindsight/hindsight-clients/go

Requires Go 1.23+.

Quick Start

<CodeSnippet code={quickstartGo} section="quickstart-full" language="go" />

API Structure

The Go client provides access to all Hindsight API operations through structured namespaces:

• `client.MemoryAPI` - Retain, recall, reflect operations
• `client.BanksAPI` - Bank management
• `client.DirectivesAPI` - Directive management
• `client.MentalModelsAPI` - Mental model management
• `client.DocumentsAPI` - Document operations
• `client.EntitiesAPI` - Entity operations
• `client.OperationsAPI` - Async operation monitoring

Working with Nullable Fields

The Go client uses NullableString, NullableTime, and similar types for optional fields:

<CodeSnippet code={quickstartGo} section="nullable-fields" language="go" />

Error Handling

<CodeSnippet code={quickstartGo} section="error-handling" language="go" />

More Examples

For detailed examples of all operations, see:

• Python SDK documentation - API concepts are the same
• Node.js SDK documentation - API concepts are the same
• OpenAPI specification - Complete API reference