hindsight/hindsight-integrations/coding-agents

One-Line Pitch

Injects Hindsight long-term project memory into DeepSeek Harness (DSH): recalls relevant context from the memory bank before each user turn and injects it into the model input; conversation content is automatically written back to repository-level memory bank at session end, with memories isolated by repository and shared across sessions.

Core Capabilities

• Before each user turn (agent/pre-step), calls the memory service for semantic retrieval, appending hit knowledge pages and context as kind: 'plugin' messages to the model input
• Listens to agent/session-start for cold-start checks, automatically runs git history import and codebase structure analysis in the background, no manual commands needed
• Automatically writes back the complete session (including tool calls and assistant replies) at agent/turn-stopping, no need to "save" when conversation ends
• Registers 8 native Cordis plugin tools (hindsight_*) for direct DSH model invocation (search/read knowledge pages, deep reasoning, capture initiative, ingest document, sync status, diagnose)
• Resolves working directory to independent "memory banks" (default naming coding-agent::<repo-name>), multiple DSH sessions won't have data bleed-through, sub-agent sessions won't be duplicated
• Three deployment modes available: Hindsight Cloud (default), self-hosted service, local daemon (127.0.0.1:9077)

Technical Implementation

• Language: TypeScript (ESM)
• Key Dependencies: @vectorize-io/hindsight-all (core client), @modelcontextprotocol/sdk (optional MCP tools path), zod (parameter validation); does not introduce DSH's own packages to avoid hard dependency on host version
• Architecture Pattern: Cordis native plugin—exports name, inject=["agents"] and apply(ctx); apply binds 4 lifecycle events via ctx.on (agent/session-start / agent/pre-step with prepend:true / agent/turn-stopping / agent/disposed), and registers native tools in the host tool registry via ctx.inject(["tools"], ...)
• Entry Files: src/dsh.ts (Cordis entry, directly loaded by DSH), src/index.ts (shared by opencode/Kilo and other plugin hosts for same core logic), cordis.patch.yml (profile load declaration)

Use Cases

Developers using DSH daily for cross-session projects—frequently modifying the same batch of files in the same repository, re-discussing already-decided values, or asking "why was this implemented this way last time?" After enabling, DSH sessions automatically recall relevant knowledge pages and historical decisions at start, and write this turn's Q&A and tool calls to the repository-level memory bank at end; next session directly inherits context without needing to restate background. Different sessions in the same repository share the same memory without interfering with each other.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:vectorize-io/hindsight/hindsight-integrations/coding-agents

Configuration Options

Config file: ~/.hindsight/coding-agent.json. Environment variables (HINDSIGHT_*) as fallback, file takes priority.

Tools visible to model: hindsight_sync_status / hindsight_diagnose / hindsight_search_knowledge_pages / hindsight_list_knowledge_pages / hindsight_read_knowledge_page / hindsight_reflect / hindsight_capture_initiative / hindsight_ingest_document.

FAQ

Q: Do I need to run any commands to initialize memory after installation?

A: No. agent/session-start automatically performs cold-start checks, pulls git history and codebase structure in the background, memory continuously supplements in background; no manual commands needed, no ingest CLI either.

Q: Where is data stored? Is it uploaded to the cloud?

A: Defaults to Hindsight Cloud (needs a Bearer Token in apiToken). Can also switch to self-hosted service (set apiUrl to your server) or local daemon (set serverMode: "daemon", plugin starts hindsight-embed on demand and listens on 127.0.0.1:9077). The three modes only affect where the service runs; HTTP interface is consistent.

Q: Will multiple DSH sessions (different projects) bleed data?

A: No. DSH's web interface can create sessions in different directories; each session's session.header.cwd determines which workspace to use; plugin resolves each workspace root directory to separate "memory banks" (default naming coding-agent::<repo-name>). Sub-agent sessions (origin === "subagent") are identified and skipped, won't be duplicated.

Q: Which layer is it installed at? Will it affect all DSH profiles?

A: Mounts to host layer via cordis.patch.yml, takes effect for all profiles; if you want to disable just one profile, change that profile's own cordis.patch.yml line to disabled: true, no need to uninstall.

Q: How to disable memory for a specific repository?

A: In ~/.hindsight/coding-agent.json under banks section, write { "disabled": true } by the resolved bank id (e.g., coding-agent::secret-client); or use optInPaths to list allowed directories and set optInOnly to true, projects outside the list are completely silent with no writes.

Q: Where do retrieval results appear?

A: Retrieved content is appended as user message with source: { kind: 'plugin', plugin: 'hindsight', form: 'recall' }, DSH renders it as "recalled material" rather than user input; the model can also proactively query using tools like hindsight_search_knowledge_pages, hindsight_reflect, etc.

Q: How to debug when errors occur?

A: Check $TMPDIR/hindsight-coding-agent/plugin.log (human-readable, sorted by LEVEL [scope] message) or /tmp/hindsight-plugin.log (machine-readable, each line JSON, reflects each recall/write success/failure). Set logLevel to debug in config to see more detailed process. Model can also directly call hindsight_diagnose tool for self-service troubleshooting.

Learning Curve

Beginner-friendly — just run dsh plugin add to load, all config options optional; if you don't want to configure, just use Hindsight Cloud + default bank naming, memory recall and writing work immediately in the repo.

Known Issues & Limitations

• Local daemon mode on macOS requires self-provided Rust toolchain: litellm as a transitive dependency of hindsight-embed only publishes Linux/Windows wheels; macOS needs to compile from source via maturin and maintain a relatively new rustc; otherwise startup fails due to missing toolchain.
• Process-level host layer registration resolves bank by startup directory by default: Tools are registered when plugin loads, first gets a template via process.cwd(); each time the model invokes, the bank is re-resolved using the caller's session workspace. If the startup directory happens to fall into some banks.<id> blacklist, tools won't be exposed for any subsequent repositories served by that process (even if their banks are enabled).
• DSH lacks toast/UI notification channel for plugins: Hosts like opencode/Kilo/Cline show "🧠 Memory Enabled" banner at startup; DSH has no corresponding channel, so no banner appears in DSH UI at startup, can only confirm from logs.
• Importing historical DSH sessions requires Node 22.15+: Older Node fails to parse Zstandard-framed JSONL under $DSH_HOME/sessions, backfill skips by reason and doesn't silently pretend success.
• No repository-level config file: Intentionally excluded local files like .hindsightrc.json in repositories to prevent cloned repos from secretly enabling or redirecting memory; path mapping and host overrides are centralized in user-level ~/.hindsight/coding-agent.json.

---

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-docs

Works 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:

• https://hindsight.vectorize.io

Clients:

• Python
• Node.js
• REST API
• CLI

Community:

• Slack
• GitHub Issues

---

Star History

Supported Platforms

⚠️ Intel Macs: use hindsight-all-slim — see the installation guide for details.

---

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE

---

Built by Vectorize.io