Data
Plugin
hindsight
Hindsight: Agent Memory That Learns
Plugin Signal84/100Strong
maintained100
capable50
documented100
adopted91
Install on Claude Code
> /plugin marketplace add vectorize-io/hindsight
Stats
19,461
Stars
1,255
Forks
Active
Maintenance
Python
Language
MIT
License
2m ago
Last commit
9mo ago
Created
Repo: vectorize-io/hindsight
What's inside
Skills
9/code-reviewReview changed code against project standards. Checks for missing tests, dead code, type safety, lint issues, and coding conventions. Run after completing any implementation work./hs-releaseCut a core Hindsight release (vX.Y.Z) and open the changelog + blog PR. Use when asked to cut/start a release, bump the version, or publish a new Hindsight version./create-agentCreate a new Hindsight-powered subagent with long-term memory. Use when the user wants a specialized agent that learns and remembers across sessions./hindsight-recallSearch long-term memory for relevant context from past coding sessions using Hindsight MCP tools/hindsight-architectExpert memory architect. Understands your application, identifies where memory adds value, and produces an implementation plan with bank config, tag schema, and code./hindsight-cloudStore team knowledge, project conventions, and learnings from tasks. Use to remember what works and recall context before new tasks. Connects to Hindsight Cloud. (user)
Show all 9 skillsShow fewer
/hindsight-docsComplete Hindsight documentation for AI agents. Use this to learn about Hindsight architecture, APIs, configuration, and best practices./hindsight-localStore user preferences, learnings from tasks, and procedure outcomes. Use to remember what works and recall context before new tasks. (user)/hindsight-self-hostedStore team knowledge, project conventions, and learnings from tasks. Use to remember what works and recall context before new tasks. Connects to a self-hosted Hindsight server. (user)
MCP
1README
1
Documentation • Paper • Cookbook • Hindsight Cloud
What is Hindsight?
Hindsight™ is an agent memory system built to create smarter agents that learn over time. Most agent memory systems focus on recalling conversation history. Hindsight is focused on making agents that learn, not just remember.
It eliminates the shortcomings of alternative techniques such as RAG and knowledge graph and delivers state-of-the-art performance on long term memory tasks.
Memory Performance & Accuracy
Hindsight is the most accurate agent memory system ever tested according to benchmark performance. It has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of January 2026 is shown here:
The benchmark performance data for Hindsight has been independently reproduced by research collaborators at the Virginia Tech Sanghani Center for Artificial Intelligence and Data Analytics and The Washington Post. Other scores are self-reported by software vendors.
Hindsight is being used in production at Fortune 500 enterprises and by a growing number of AI startups.
Adding Hindsight to Your AI Agents
The easiest way to use Hindsight with an existing agent is with the LLM Wrapper. You can add memory to your agent with 2 lines of code. That will swap your current LLM client out with the Hindsight wrapper. After that, memories will be stored and retrieved automatically as you make LLM calls.
If you need more control over how and when your agent stores and recalls memories, there's also a simple API you can integrate with using the SDKs or directly via HTTP.
🤖 Using a coding agent? Install the Hindsight documentation skill for instant access to docs while you code:
npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docsWorks with Claude Code, Cursor, and other AI coding assistants.
Quick Start
Docker (recommended)
export OPENAI_API_KEY=sk-xxx
docker run -it --pull always --name hindsight --restart unless-stopped -p 8888:8888 -p 9999:9999 \
-e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
-v hindsight-data:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
API: http://localhost:8888 UI: http://localhost:9999
You can modify the LLM provider by setting HINDSIGHT_API_LLM_PROVIDER. Valid options are openai, anthropic, gemini, groq, ollama, lmstudio, minimax, and atlas (Atlas Cloud). The documentation provides more details on supported models.
Docker (external PostgreSQL)
export OPENAI_API_KEY=sk-xxx
export HINDSIGHT_DB_PASSWORD=choose-a-password
cd docker/docker-compose
docker compose up
Oracle AI Database is also supported for enterprise deployments with full feature parity. See the storage documentation for details.
API: http://localhost:8888 UI: http://localhost:9999
Client
pip install hindsight-client -U
# or
npm install @vectorize-io/hindsight-client
Python
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
# Retain: Store information
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")
# Recall: Search memories
client.recall(bank_id="my-bank", query="What does Alice do?")
# Reflect: Generate disposition-aware response
client.reflect(bank_id="my-bank", query="Tell me about Alice")
Node.js / TypeScript
npm install @vectorize-io/hindsight-client
const { HindsightClient } = require('@vectorize-io/hindsight-client');
const main = async () => {
const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
await client.retain('my-bank', 'Alice loves hiking in Yosemite');
const results = await client.recall('my-bank', 'What does Alice like?');
console.log(results);
}
main();
Python Embedded (no server required)
pip install hindsight-all -U
On Intel (x86_64) Macs, install hindsight-all-slim instead — see Supported Platforms.
import os
from hindsight import HindsightServer, HindsightClient
with HindsightServer(
llm_provider="openai",
llm_model="gpt-5-mini",
llm_api_key=os.environ["OPENAI_API_KEY"]
) as server:
client = HindsightClient(base_url=server.url)
client.retain(bank_id="my-bank", content="Alice works at Google")
results = client.recall(bank_id="my-bank", query="Where does Alice work?")
Use Cases
Hindsight is built to support conversational AI agents as well as agents that are intended to perform tasks autonomously. The ideal use case for Hindsight are agents that require a blend of these features such as AI employees that need to handle open-ended tasks, change behavior based on user feedback, and learn to perform complex tasks to automate work at a level that approximates a human work. Hindsight can be used with simple AI workflows like those built with n8n and other similar tools, but may be overkill for such applications.
Per-User Memories and Chat History
One of the simpler use cases you can use Hindsight for is to personalize AI chatbots and other conversational agents by storing and recalling memories associated with individual users.
The requirements for this use case usually look something like this:
Satisfying these requirements in Hindsight is straightforward. When new user inputs and tool calls are ingested into Hindsight using the retain operation, custom metadata can be used to enrich the new memories. Metadata provides a convenient way to isolate memories that need to be restricted to a given user. Once these are fed into the retain operation, any raw memories and mental models that get created can be filtered when retrieving relevant memories.
Architecture & Operations
Most agent memory implementations rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:
- World: Facts about the world ("The stove gets hot")
- Experiences: Agent's own experiences ("I touched the stove and it really hurt")
- Mental Models: Learned understanding of the agent's world formed by reflecting on raw memories and experiences.
Memories in Hindsight are stored in banks (i.e. memory banks). When memories are added to Hindsight, they are pushed into either the world facts or experiences memory pathway. They are then represented as a combination of entities, relationships, and time series with sparse/dense vector representations to aid in later recall.
Hindsight provides three simple methods to interact with the system:
- Retain: Provide information to Hindsight that you want it to remember
- Recall: Retrieve memories from Hindsight
- Reflect: Reflect on memories and experiences to generate new observations and insights from existing memories.
Retain
The retain operation is used to push new memories into Hindsight. It tells Hindsight to retain the information you pass in as an input.
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
# Simple
client.retain(
bank_id="my-bank",
content="Alice works at Google as a software engineer"
)
# With context and timestamp
client.retain(
bank_id="my-bank",
content="Alice got promoted to senior engineer",
context="career update",
timestamp="2025-06-15T10:00:00Z"
)
Behind the scenes, the retain operation uses an LLM to extract key facts, temporal data, entities, and relationships. It passes these through a normalization process to transform extracted data into canonical entities, time series, and search indexes along with metadata. These representations create the pathways for accurate memory retrieval in the recall and reflect operations.
Recall
The recall operation is used to retrieve memories. These memories can come from any of the memory types (world, experiences, etc.)
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
# Simple
client.recall(bank_id="my-bank", query="What does Alice do?")
# Temporal
client.recall(bank_id="my-bank", query="What happened in June?")
Recall performs 4 retrieval strategies in parallel:
- Semantic: Vector similarity
- Keyword: BM25 exact matching
- Graph: Entity/temporal/causal links
- Temporal: Time range filtering
The individual results from the retrievals are merged, then ordered by relevance using reciprocal rank fusion and a cross-encoder reranking model.
The final output is trimmed as needed to fit within the token limit.
Reflect
The reflect operation is used to perform a more thorough analysis of existing memories. This allows the agent to form new connections between memories and build a more thorough understanding of its world.
For example, the reflect operation can be used to support use cases such as:
- An AI Project Manager reflecting on what risks need to be mitigated on a project.
- A Sales Agent reflecting on why certain outreach messages have gotten responses while others haven't.
- A Support Agent reflecting on opportunities where customers have questions not answered by current product documentation.
The reflect operation can also be used to handle on-demand question answering or analysis which require more deep thinking.
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")
client.reflect(bank_id="my-bank", query="What should I know about Alice?")
Resources
Documentation:
Clients:
Community:
Star History
Supported Platforms
| Platform | Docker | Bare Metal (pip) | Embedded DB (pg0) |
|---|---|---|---|
| Linux (x86_64, ARM64) | ✅ | ✅ | ✅ |
| macOS (Apple Silicon / arm64) | ✅ | ✅ | ✅ |
| macOS (Intel / x86_64) | ✅ | ⚠️ | ✅ |
| Windows (x86_64) | ✅ | ✅ | ✅ |
⚠️ Intel Macs: use hindsight-all-slim — see the installation guide for details.
Contributing
See CONTRIBUTING.md.
License
MIT — see LICENSE
Built by Vectorize.io
File tree
1778vectorize-io/hindsightView on GitHub
.claude/
.claude-plugin/
marketplace.json
skills/
code-review/
SKILL.md
hs-release/
SKILL.md
.dockerignore
.env.example
.githooks/
pre-commit
.github/
ISSUE_TEMPLATE/
bug_report.yml
config.yml
feature_request.yml
star-history/
chart.svg
data.json
workflows/
deploy-docs.yml
perf-test.yml
release-integration.yml
release-tool.yml
release.yml
sign-images.yml
star-history.yml
test.yml
windows-smoke.yml
.gitignore
.prettierrc.json
.python-version
AGENTS.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
cookbook/
README.md
deno.lock
docker/
docker-compose/
alloydb/
docker-compose.yaml
claude-code/
docker-compose.yaml
README.md
custom-models/
docker-compose.yaml
Dockerfile
README.md
external-pg/
docker-compose.yaml
local-llm/
docker-compose.yaml
README.md
nginx/
docker-compose.yml
nginx.conf
README.md
pg_search/
docker-compose.yaml
Dockerfile
pg_textsearch/
docker-compose.yaml
Dockerfile
pgroonga/
docker-compose.yaml
Dockerfile
s3-file-storage/
docker-compose.yaml
s3.json
timescale/
.dockerignore
.env.example
docker-compose.yaml
Dockerfile
README.md
vchord/
docker-compose.yaml
standalone/
Dockerfile
start-all.sh
test-start-all.sh
test-image.sh
test-slim-local.sh
docs/
superpowers/
plans/
2026-07-25-v2-knowledge-pages.md
specs/
2026-07-25-v2-knowledge-pages-design.md
2026-07-27-reflect-pages-runtime.md
helm/
hindsight/
.helmignore
Chart.yaml
README.md
templates/
_helpers.tpl
api-deployment.yaml
api-model-cache-pvc.yaml
api-service.yaml
controlplane-deployment.yaml
controlplane-service.yaml
hpa.yaml
ingress.yaml
NOTES.txt
pdb.yaml
postgresql-service.yaml
postgresql-statefulset.yaml
secret.yaml
serviceaccount.yaml
tei-embedding-deployment.yaml
tei-embedding-service.yaml
tei-reranker-deployment.yaml
tei-reranker-service.yaml
worker-service.yaml
worker-statefulset.yaml
values.yaml
hindsight-all/
hindsight-all-npm/
.gitignore
package.json
README.md
src/
command.test.ts
command.ts
index.ts
logger.ts
server.test.ts
server.ts
types.ts
tsconfig.json
tsup.config.ts
vitest.config.ts
hindsight-all-slim/
pyproject.toml
README.md
hindsight/
__init__.py
api_namespaces.py
client_wrapper.py
embedded.py
py.typed
server.py
pyproject.toml
README.md
tests/
__init__.py
README.md
test_cleanup_timeout.py
test_embedded_namespaces.py
test_embedded.py
test_server_integration.py
hindsight-api/
hindsight-api-slim/
hindsight_api/
__init__.py
_pg_search.py
_thread_limits.py
_vector_index.py
admin/
__init__.py
cli.py
alembic/
_dialect.py
env.py
README
script.py.mako
versions/
2071c7518f88_add_memory_links_bank_id_index.py
2eee35aa3cfc_case_insensitive_entities_trgm_index.py
5a366d414dce_initial_schema.py
86f7a033d372_repair_mental_models_subtype_at_head.py
8c6fa6f7230b_merge_v053_divergent_heads.py
9f8e7d6c5b4a_memory_links_deferrable_fk.py
a1b2c3d4e5f6_add_file_storage_table.py
a1c9e7f3b2d8_observation_history_drop_memory_units_fk.py
a1d3f5b7c9e2_widen_remaining_bank_id_to_text.py
a2b3c4d5e6f7_add_text_signals_column.py
a2b3c4d5e6f8_add_gin_index_source_memory_ids.py
a2v3w4x5y6z7_add_last_refreshed_source_query.py
a3b4c5d6e7f8_add_consolidation_failed_at_to_memory_units.py
a4b5c6d7e8f9_fix_per_bank_vector_index_type.py
a7b8c9d0e1f2_split_history_into_own_tables.py
a8c1e4f7b0d3_add_operation_retention_indexes.py
a9b8c7d6e5f4_add_knowledge_pages.py
aa2b3c4d5e6f_nullable_event_date.py
b2d4f6a8c1e3_repair_maintenance_routines_public.py
b3c4d5e6f7a8_add_content_hash_to_chunks.py
b3c4d5e6f7g8_add_temporal_date_indexes.py
b3e8d1c6f4a9_entity_kind_partial_trgm_index.py
b3w4x5y6z7a8_add_structured_content_to_mental_models.py
b4c5d6e7f8a9_backfill_observation_scopes.py
b57a7c9e0d13_add_bank_stats_cache.py
b5a4c3e2f1d8_add_graph_maintenance_queue.py
b5d4e3f2a1c9_backfill_entity_cooccurrences_event_time.py
b6d2f8a4c1e7_maintenance_routines_schema_local.py
b7c4d8e9f1a2_add_chunks_table.py
b8c9d0e1f2a3_vchord_cosine_opclass.py
c1a2b3d4e5f6_enable_pg_trgm_and_entities_trgm_index.py
c1d2e3f4a5b6_merge_graph_queue_and_vchord_heads.py
c2d3e4f5g6h7_add_audit_log_table.py
c3d4e5f6g7h8_add_history_to_mental_models.py
c3e5a7b9d1f4_widen_history_bank_id_to_text.py
c3f7a1b9d2e4_backfill_observation_search_vector.py
c4x5y6z7a8b9_backsweep_orphan_observations_v2.py
c5d6e7f8a9b0_add_bank_id_to_memory_links.py
c7d1e9a4b3f2_add_archive_causal_links.py
c7e9f1a3b5d2_maintenance_routines_skip_vanished_schemas.py
c8e5f2a3b4d1_add_retain_params_to_documents.py
c9a1b2d3e4f5_add_invalidated_memory_units.py
d2e3f4a5b6c7_add_memory_links_expansion_indexes.py
d3e4f5a6b7c8_add_llm_requests_table.py
d4e5f6g7h8i9_gin_source_memory_ids_fastupdate_off.py
d4f6a8c2e1b3_drop_archive_embedding_column.py
d5e6f7a8b9c0_add_bank_internal_id_and_per_bank_hnsw.py
d5y6z7a8b9c0_backfill_mental_models_subtype.py
d6e7f8a9b0c1_drop_documents_metadata_column.py
d7b2f8a1c934_add_schemas_with_expired_operations_routine.py
d9f6a3b4c5e2_rename_bank_to_interactions.py
e0a1b2c3d4e5_disposition_to_3_traits.py
e1b2c3d4f5a6_drop_unused_indexes.py
e1f2a3b4c5d6_merge_heads_embedding_drop_and_links_index.py
e4a7c1b9d2f6_drop_memory_units_access_count.py
e4f5a6b7c8d9_add_webhooks_tables.py
e5f6a7b8c9d0_add_maintenance_routines.py
e5f6g7h8i9j0_cascade_delete_ops_on_bank_delete.py
e7c3a9f1b2d5_drop_archive_search_vector_column.py
e9b2c7d1f3a4_drop_entity_memory_links.py
f1a2b3c4d5e6_add_memory_links_composite_index.py
f2a6d8c4b1e9_drop_stale_global_memory_units_vector_index.py
f4d1c2b3a5e6_add_scheduled_mental_model_refresh_routine.py
f6g7h8i9j0k1_chunk_fk_cascade_delete.py
f7g8h9i0j1k2_add_webhook_http_config.py
g2a3b4c5d6e7_add_tags_column.py
g2h3i4j5k6l7_remove_opinion_fact_type.py
g7h8i9j0k1l2_backsweep_orphan_observations.py
h3c4d5e6f7g8_mental_models_v4.py
h3i4j5k6l7m8_merge_heads_and_add_unit_entities_index.py
i4d5e6f7g8h9_delete_opinions.py
i4j5k6l7m8n9_add_cancelled_status_to_async_operations.py
j5e6f7g8h9i0_mental_model_versions.py
k6f7g8h9i0j1_add_directive_subtype.py
k6l7m8n9o0p1_create_observation_sources_table.py
l7g8h9i0j1k2_add_worker_columns.py
m3rg3h3ad5f6_merge_deferrable_fk_and_cooccurrence_backfill.py
m8h9i0j1k2l3_mental_model_id_to_text.py
n9i0j1k2l3m4_learnings_and_pinned_reflections.py
o0j1k2l3m4n5_migrate_mental_models_data.py
o1a2b3c4d5e6_oracle_baseline.py
p1k2l3m4n5o6_new_knowledge_architecture.py
p4q5r6s7t8u9_configurable_bm25_language.py
q2l3m4n5o6p7_fix_mental_model_fact_type.py
r3m4n5o6p7q8_add_reflect_response_to_reflections.py
rename_personality_to_disposition.py
s4n5o6p7q8r9_add_consolidated_at_to_memory_units.py
t5o6p7q8r9s0_rename_mental_models_to_observations.py
u6p7q8r9s0t1_mental_models_text_id.py
v7q8r9s0t1u2_add_max_tokens_to_mental_models.py
w8r9s0t1u2v3_fix_mental_models_pk_isolation.py
x9s0t1u2v3w4_add_bank_config_column.py
y0t1u2v3w4x5_add_result_metadata_gin_index.py
z1u2v3w4x5y6_add_observation_tags_to_memory_units.py
api/
__init__.py
disconnect.py
http.py
mcp.py
page_markdown.py
banner.py
cancellation.py
config_resolver.py
config.py
daemon.py
db_url.py
engine/
__init__.py
audit.py
bank_attribution.py
bank_stats_cache.py
causal_links.py
chinese_temporal_periods.py
consolidation/
__init__.py
consolidator.py
prompts.py
cross_encoder.py
db/
db_budget.py
db_utils.py
__init__.py
base.py
ops_oracle.py
ops_postgresql.py
ops.py
optional_routines.py
oracle.py
pool_instrumentation.py
postgresql.py
result.py
directives/
__init__.py
models.py
embeddings.py
entity_resolver.py
graph_maintenance.py
interface.py
jina_mlx_reranker.py
llm_interface.py
llm_trace.py
llm_wrapper.py
local_device.py
maintenance.py
memories/
__init__.py
base.py
pg/
__init__.py
counts.py
curation.py
graph.py
reads.py
writes.py
postgres.py
memory_engine.py
mental_model_refresh.py
multi_llm.py
operation_metadata.py
parsers/
__init__.py
base.py
iris.py
llama_parse.py
markitdown.py
prompt_utils.py
providers/
__init__.py
anthropic_llm.py
claude_code_llm.py
codex_auth.py
codex_llm.py
fireworks_llm.py
gemini_cache.py
gemini_llm.py
litellm_llm.py
litellm_router_llm.py
llamacpp_llm.py
llm_debug.py
mock_llm.py
none_llm.py
nous_auth.py
nous_llm.py
openai_compatible_llm.py
openai_responses_llm.py
query_analyzer.py
reflect/
__init__.py
agent.py
delta_ops.py
models.py
observations.py
prompts.py
structured_doc.py
tokenization.py
tools_schema.py
tools.py
response_models.py
retain/
__init__.py
bank_utils.py
chunk_storage.py
embedding_processing.py
embedding_utils.py
entity_labels.py
entity_processing.py
fact_extraction.py
fact_storage.py
link_creation.py
link_utils.py
orchestrator.py
types.py
schema.py
search/
__init__.py
fusion.py
graph_retrieval.py
link_expansion_retrieval.py
recall_boost.py
reranking.py
retrieval.py
tags.py
temporal_extraction.py
think_utils.py
trace.py
tracer.py
types.py
sql/
__init__.py
... 1600 moreShowing a partial view of a very large repo.
FAQ
hindsight is a Claude Code plugin with 9 hand-picked skills for data work, indexed on Flowy. Install it with the command on its page. It includes code-review, hs-release, create-agent. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is hindsight?
- Hindsight: Agent Memory That Learns
- How do I install hindsight?
- Run these in Claude Code: /plugin marketplace add vectorize-io/hindsight. Then prompt normally.
- Does hindsight auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is hindsight free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.