hindsight/hindsight-integrations/coding-agents

一句话定位

给 DeepSeek Harness（DSH）注入 Hindsight 长期项目记忆：每个用户回合开始前从记忆银行召回相关上下文注入到模型输入，对话内容在结束时自动写回仓库级记忆银行，记忆按仓库隔离、跨会话共享。

核心能力

• 在每轮用户回合（agent/pre-step）前调用记忆服务做语义检索，把命中的知识页与上下文作为 kind: 'plugin' 消息追加到模型输入
• 监听 agent/session-start 做冷启动检查，自动后台启动 git 历史导入与代码库结构调研，无须手动命令
• 在 agent/turn-stopping 自动写回本轮完整会话（包括工具调用与助手回复），会话结束无须"另存"
• 以原生 Cordis 插件方式注册 8 个 hindsight_* 工具给 DSH 模型直接调用（搜索/读取知识页、深度推理、捕获计划、摄入文档、同步状态、诊断）
• 按工作目录解析到独立的"记忆银行"（默认命名 coding-agent::<仓库名>），多个 DSH 会话不会串数据，子代理会话不会重复落库
• 三种部署模式可选：Hindsight Cloud（默认）、自托管服务、本机守护进程（127.0.0.1:9077）

技术实现

• 语言: TypeScript（ESM）
• 关键依赖: @vectorize-io/hindsight-all（核心客户端）、@modelcontextprotocol/sdk（MCP 工具可选路径）、zod（参数校验）；不引入 DSH 自身的包，避免对宿主版本的硬依赖
• 架构模式: Cordis 原生插件——导出 name、inject=["agents"] 与 apply(ctx)；apply 通过 ctx.on 绑定 4 个生命周期事件（agent/session-start / agent/pre-step 带 prepend:true / agent/turn-stopping / agent/disposed），并通过 ctx.inject(["tools"], ...) 在宿主工具注册表注册原生工具
• 入口文件: src/dsh.ts（Cordis 入口，DSH 直接加载），src/index.ts（opencode/Kilo 等插件宿主复用同一份核心逻辑），cordis.patch.yml（profile 装载声明）

适用场景

日常用 DSH 做跨会话项目的开发者——经常在同一个仓库里反复修改同一批文件、重新讨论已决定过的取值、或者问"上次为什么这样实现"。开启后，DSH 会话开始时自动召回相关知识页与历史决策，结束时把这一轮的问答与工具调用一并写入仓库级记忆银行；下次会话直接继承上下文，不必每次复述背景。同一仓库的不同会话共享同一份记忆，互不干扰。

前置依赖与兼容性

安装方式

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

配置项

配置文件：~/.hindsight/coding-agent.json。环境变量（HINDSIGHT_*）作为兜底层，文件优先。

模型可见的工具：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。

常见问题

Q: 安装后还需要跑什么命令初始化记忆吗？

A: 不需要。agent/session-start 会自动做冷启动检查，后台拉取 git 历史与代码库结构，记忆在后台持续补充；无须手动命令，也没有 ingest CLI。

Q: 数据存在哪里？会上传到云端吗？

A: 默认指向 Hindsight Cloud（需在 apiToken 里给一个 Bearer Token）。也可以改为自托管服务（设 apiUrl 为你的服务端）或本机守护进程（设 serverMode: "daemon"，插件按需启动 hindsight-embed 并监听 127.0.0.1:9077）。三种模式只影响服务跑在哪，HTTP 接口一致。

Q: 多个 DSH 会话（不同项目）会串数据吗？

A: 不会。DSH 的 Web 界面可在不同目录创建会话，每个会话的 session.header.cwd 决定走哪个工作区；插件按工作区根目录分别解析到独立的"记忆银行"（默认命名 coding-agent::<仓库名>）。子代理会话（origin === "subagent"）会被识别并跳过，不会被重复入库。

Q: 安装在哪一层，会影响所有 DSH profile 吗？

A: 通过 cordis.patch.yml 把插件挂到宿主层，对所有 profile 生效；若只想关掉某一个 profile，把那一个 profile 自己的 cordis.patch.yml 里把这一行改成 disabled: true 即可，无须卸载。

Q: 如何停用某个仓库的记忆？

A: 在 ~/.hindsight/coding-agent.json 的 banks 节里按解析后的银行 id（例如 coding-agent::secret-client）写 { "disabled": true }；或者用 optInPaths 列允许的目录并把 optInOnly 设 true，列表外的项目完全静默、不落库。

Q: 检索结果会出现在哪？

A: 检索到的内容被追加为 source: { kind: 'plugin', plugin: 'hindsight', form: 'recall' } 的用户消息，DSH 会作为"召回材料"渲染而不是用户输入；模型自己也可以调用 hindsight_search_knowledge_pages、hindsight_reflect 等工具主动查询。

Q: 出错了怎么排查？

A: 看 $TMPDIR/hindsight-coding-agent/plugin.log（人读，按 LEVEL [scope] message 排）或 /tmp/hindsight-plugin.log（机器读，每条 JSON 行，反映每次 recall/写库成功失败）。在配置里把 logLevel 调到 debug 可看到更细的过程。模型也可直接调 hindsight_diagnose 工具自助排查。

上手难度

入门 —— dsh plugin add 一行即可装载，配置项全部可选；不愿配就用 Hindsight Cloud + 默认银行命名，仓库里立刻能召回与落库。

已知问题与限制

• 本机守护进程模式在 macOS 上需要自备 Rust 工具链：litellm 作为 hindsight-embed 的传递依赖仅发布 Linux/Windows 的 wheel，macOS 需通过 maturin 从源码编译并维持较新的 rustc；否则启动会以缺工具链失败。
• 进程级宿主层注册默认走启动目录的银行解析：工具注册在插件加载时完成，先按 process.cwd() 拿一个模板；每次模型调用时再用调用者所在会话的工作区重新解析银行。若启动目录恰好落在某个 banks.<id> 黑名单里，工具在该进程后续服务的所有仓库都不会暴露（即便它们的银行是开启的）。
• DSH 没有插件面向的 toast/UI 通知通道：opencode/Kilo/Cline 这类宿主会在启动时显示"🧠 已启用记忆"横幅，DSH 上没有对应渠道，所以 DSH 启动时不会在 UI 里看到横幅提示，只能从日志确认。
• 导入历史 DSH 会话需 Node 22.15+：老 Node 解析 $DSH_HOME/sessions 下的 Zstandard 帧化 JSONL 会失败，回填会按原因跳过、不会静默假装成功。
• 没有仓库级配置文件：刻意没有仓库内 .hindsightrc.json 之类的本地文件，防止克隆下来的仓库偷偷开启或重定向记忆；按路径映射与按宿主覆盖都集中在用户级 ~/.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