# hindsight

> Add Hindsight long-term project memory to DeepSeek Harness: automatically recall knowledge pages and context each session, conversations auto-saved, shared memory bank per repository.

## Metadata

- Author: [@vectorize-io](https://github.com/vectorize-io)
- Repo: <https://github.com/vectorize-io/hindsight.git>
- GitHub: [vectorize-io/hindsight](https://github.com/vectorize-io/hindsight)
- Stars: 20,095
- Language: Python
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://hindsight.vectorize.io/>
- Topics: `agentic-ai`, `agents`, `ai-memory`, `memory`
- Forks: 1,423
- Open Issues: 140
- Last push: 2026-08-17T15:29:26.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

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

## Wiki

## 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
| Dependency | Min Version | Description |
|---|---|---|
| DeepSeek Harness | Not declared | This plugin mounts to host layer as Cordis native plugin; loads as long as DSH still uses event names `agent/session-start`, `agent/pre-step`, `agent/turn-stopping`, `agent/disposed`. |
| Node.js | Not declared | `package.json` doesn't declare `engines`; if need to import historical dsh sessions for bulk backfill, Zstandard decoding requires Node 22.15+. |
| Platform | Cross-platform | Cross-platform. In `daemon` mode, macOS needs self-provided Rust toolchain for `litellm` (no wheel); Linux/Windows install wheel directly. |
| Native Modules | None | `package.json` doesn't declare native module dependencies. `daemon` mode indirectly depends on `hindsight-embed`'s own requirements. |

## Installation
```bash
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.

| Config | Type | Description | Default |
|---|---|---|---|
| `serverMode` | `"cloud"` \| `"self-hosted"` \| `"daemon"` | Where the memory service runs | `cloud` |
| `apiUrl` | string | Hindsight API address (auto-changed to `http://127.0.0.1:{apiPort}` in `daemon` mode) | `https://api.hindsight.vectorize.io` |
| `apiToken` | string | Bearer Token required for Cloud mode | — |
| `bankId` | string | Explicitly specify memory bank id; if unset, resolves dynamically by repository | Resolved by directory |
| `bankIdTemplate` | string | Dynamic bank id template, supports placeholders `{gitProject}` `{project}` `{harness}` `{channel}` `{user}` | `coding-agent::{gitProject}` |
| `mapPathToBank` | object | Absolute path → bank id mapping, longest prefix first, can override default entirely | — |
| `optInOnly` | boolean | Only enable memory in whitelisted directories, other directories silently skip writing | `false` |
| `optInPaths` | string[] | Whitelisted directories (prefix matching, auto-expands `~`), each repo still retains separate bank | `[]` |
| `disabled` | boolean | Hard disable—plugin completely inactive, no banks created | `false` |
| `retainSessions` | boolean | Whether plugin host (opencode/Kilo) writes back per turn asynchronously | `true` |
| `reflectTimeoutMs` | number | Timeout for recall call at session start (milliseconds) | `120000` |
| `pageRefreshEveryTurns` | number | Refresh knowledge pages every how many user turns | `10` |
| `autoSeed` | boolean | Cold repositories automatically seed from git history | `true` |
| `seedLimit` | number | Maximum recent commits for auto-seed | `300` |
| `codebaseSurvey` | boolean | Whether cold repositories run a read-only codebase structure survey | `true` |
| `surveyModel` | string | Model for survey (Claude recipe) | `haiku` |
| `surveyBudgetUsd` | number | Survey budget cap (Claude recipe) | `2` |
| `gitIngest` | `"message"` \| `"full"` \| `"none"` | Git history ingestion depth: `message` only commit messages; `full` includes diff; `none` disables | `message` |
| `maxParallelRetains` | number | Max concurrent write requests (lower if hitting 429) | `10` |
| `retainTags` | string[] | Auto-attached tags per write, supports above placeholders | `[]` |
| `retainMetadata` | object | Auto-attached metadata per write, supports above placeholders | `{}` |
| `harnesses.<name>` | object | Override any field by host name (e.g., disable memory for Claude Code alone) | — |
| `banks.<id>` | object | Override any field by resolved bank id; can set `bank` to rename and merge into other bank | — |
| `logLevel` | `"debug"` \| `"info"` \| `"warn"` \| `"error"` | Log level | `info` |

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`.

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [hindsight](https://deepseek-plugin.org/plugins/vectorize-io/hindsight/hindsight-integrations/coding-agents)
Wiki generated by AI (model: `MiniMax-M2.5`)