# How to Configure and Utilize the Hindsight Memory System in omp

> Configure and utilize the Hindsight memory system in omp. Use retain, recall, and reflect for persistent cross-session storage and retrieval of facts via a remote vector store.

- Repository: [Can Bölük/oh-my-pi](https://github.com/can1357/oh-my-pi)
- Tags: how-to-guide
- Published: 2026-05-21

---

**Configure the Hindsight memory system in `omp` by setting `memory.backend: hindsight` in your configuration, which exposes three tools—`retain`, `recall`, and `reflect`—for persistent cross-session storage and retrieval of facts via a remote vector-store service.**

`omp` (Oh-My-Pi) implements optional long-term memory capabilities through integration with the **Hindsight** vector-store service. To enable persistent knowledge across coding sessions, you must explicitly activate the Hindsight backend and configure its connection parameters, after which the agent can store and retrieve facts automatically or via explicit tool calls.

## Enabling the Hindsight Backend

All Hindsight configuration resides under the `hindsight.*` namespace in [`packages/coding-agent/src/config/settings-schema.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/config/settings-schema.ts). To activate the feature, set `memory.backend` to `"hindsight"` in your `~/.omp/config.yml` file.

```yaml
memory:
  backend: hindsight
hindsight:
  apiUrl: https://hindsight.vectorize.io
  apiToken: <your-bearer-token>
  scoping: per-project
  autoRecall: true
  autoRetain: true
  retainEveryNTurns: 4
  mentalModelsEnabled: true

```

Valid options for `memory.backend` include `off`, `local`, or `hindsight`. When set to `hindsight`, the UI automatically reveals the Memory tab and bootstraps a `HindsightSessionState` object for every `ToolSession` via the logic in [`packages/coding-agent/src/hindsight/backend.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/backend.ts).

## Core Architecture and Components

The Hindsight integration consists of several coordinated components defined in the source tree:

- **`HindsightSessionState`** ([`packages/coding-agent/src/hindsight/state.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/state.ts)): Holds the HTTP client, the in-memory retain queue, and auto-recall logic. Accessed via `session.getHindsightSessionState()`.
- **`HindsightApi`** ([`packages/coding-agent/src/hindsight/client.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/client.ts)): Thin wrapper around REST endpoints including `/memories`, `/memories/recall`, and `/memories/reflect`.
- **Bank Scoping** ([`packages/coding-agent/src/hindsight/bank.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/bank.ts)): Determines the memory namespace using `global`, `per-project`, or `per-project-tagged` strategies.
- **Mental Models** ([`packages/coding-agent/src/hindsight/mental-models.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/mental-models.ts)): Optional curated summaries that auto-seed new banks when `hindsight.mentalModelAutoSeed` is enabled.

## The Three Memory Tools

Once enabled, the agent gains access to three tools: `retain`, `recall`, and `reflect`. Each tool is conditionally exported via `createIf` factories that verify `memory.backend = "hindsight"`.

### Retaining Facts with the Retain Tool

The `retain` tool ([`packages/coding-agent/src/tools/hindsight-retain.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/tools/hindsight-retain.ts)) accepts an array of memory items and enqueues them for asynchronous batch insertion.

```typescript
await omp.runTool("retain", {
  items: [
    { content: "The API endpoint for the order service is /v1/orders", context: "src/api.ts" },
    { content: "Feature flag X is enabled for beta users" }
  ]
});
// Returns: "2 memories queued."

```

Behind the scenes, `HindsightRetainTool.execute` calls `state.enqueueRetain(content, context)`, storing items in a `HindsightRetainQueue`. The queue flushes automatically when it reaches **16** items (`RETAIN_FLUSH_BATCH_SIZE`) or after **5 seconds** of inactivity (`RETAIN_FLUSH_INTERVAL_MS`), issuing a single `POST /memories` batch request via `HindsightApi.retainBatch`. Server-side failures surface as UI warnings rather than LLM errors.

### Recalling Facts with the Recall Tool

The `recall` tool ([`packages/coding-agent/src/tools/hindsight-recall.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/tools/hindsight-recall.ts)) queries the remote store and returns formatted results.

```typescript
const result = await omp.runTool("recall", {
  query: "order service endpoint",
  budget: "mid",
  maxTokens: 1024
});

```

The tool invokes `POST /memories/recall` through the session's client, then formats hits into a plain-text bullet list using the logic documented in [`docs/tools/recall.md`](https://github.com/can1357/oh-my-pi/blob/main/docs/tools/recall.md). No session state is mutated during recall.

### Synthesizing Knowledge with the Reflect Tool

The `reflect` tool ([`packages/coding-agent/src/tools/hindsight-reflect.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/tools/hindsight-reflect.ts)) operates similarly to `recall` but targets the `/memories/reflect` endpoint, which aggregates and summarizes matching memories rather than returning raw hits.

```typescript
const summary = await omp.runTool("reflect", {
  query: "What does the order service do?"
});

```

According to [`docs/tools/reflect.md`](https://github.com/can1357/oh-my-pi/blob/main/docs/tools/reflect.md), this produces a synthesized answer like "The order service provides CRUD operations for order resources," drawing from all relevant stored facts.

## Bank Scoping and Isolation

Memory isolation is controlled by `hindsight.scoping` in [`packages/coding-agent/src/hindsight/bank.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/bank.ts). The setting determines how the bank ID is derived:

- **`global`**: All sessions share a single global bank.
- **`per-project`**: Each project directory receives its own isolated bank.
- **`per-project-tagged`**: Project-scoped banks with additional tagging metadata.

If `hindsight.bankId` is explicitly defined, it overrides the scoping logic entirely.

## Mental Models and System Prompts

When `hindsight.mentalModelsEnabled` is true, the backend loads curated "reflect summaries" into the system prompt. If `hindsight.mentalModelAutoSeed` is also enabled, [`packages/coding-agent/src/hindsight/mental-models.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/mental-models.ts) automatically creates built-in seed models for new banks, ensuring conventions and architectural decisions persist across sessions without manual ingestion.

## Automatic Memory Management

Hindsight supports fully automated workflows via two settings:

- **`hindsight.autoRecall`**: Triggers a hidden recall query on the first turn of every session, injecting recent relevant memories into the system prompt.
- **`hindsight.autoRetain`**: Automatically enqueues transcript segments every `N` turns (controlled by `hindsight.retainEveryNTurns` and `hindsight.retainOverlapTurns`). The default `retainMode` of `full-session` upserts one document per session, while `last-turn` creates chunked entries.

These features provide seamless long-term context without explicit tool calls.

## Summary

- Set `memory.backend: hindsight` in `~/.omp/config.yml` to enable the integration.
- Configure `hindsight.apiUrl`, `hindsight.scoping`, and authentication tokens in [`packages/coding-agent/src/config/settings-schema.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/config/settings-schema.ts) options.
- Use the **`retain`** tool to queue facts for asynchronous batch insertion (flush at 16 items or 5 seconds).
- Use the **`recall`** tool to retrieve raw matching memories from the remote vector store.
- Use the **`reflect`** tool to generate synthesized answers aggregated across multiple memories.
- Enable **`hindsight.autoRetain`** and **`hindsight.autoRecall`** for hands-free memory management across sessions.

## Frequently Asked Questions

### How do I disable Hindsight after enabling it?

Set `memory.backend: off` in your `~/.omp/config.yml` file and restart the agent. According to the `createIf` factories in the tool definitions, the `retain`, `recall`, and `reflect` tools are only exported when the backend is explicitly set to `"hindsight"`, effectively disabling the feature immediately.

### What happens if the Hindsight service is unreachable?

The `HindsightApi` client in [`packages/coding-agent/src/hindsight/client.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/client.ts) handles HTTP errors gracefully. For retain operations, failures during the async flush appear as UI warnings rather than exceptions thrown to the LLM, ensuring that transient network issues do not interrupt coding sessions. Recall and reflect operations return empty results when the service is unavailable.

### Can I use different memory banks for different projects?

Yes. Set `hindsight.scoping: per-project` or `hindsight.scoping: per-project-tagged` in your configuration. The logic in [`packages/coding-agent/src/hindsight/bank.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/hindsight/bank.ts) derives the bank ID from the project directory path, ensuring isolation between codebases. Alternatively, specify a fixed `hindsight.bankId` to share memories across specific projects while keeping them separate from others.

### What is the difference between `recall` and `reflect`?

**Recall** ([`packages/coding-agent/src/tools/hindsight-recall.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/tools/hindsight-recall.ts)) returns a formatted list of individual memory hits as raw text, suitable when you need specific facts or timestamps. **Reflect** ([`packages/coding-agent/src/tools/hindsight-reflect.ts`](https://github.com/can1357/oh-my-pi/blob/main/packages/coding-agent/src/tools/hindsight-reflect.ts)) sends the query to the `/memories/reflect` endpoint, which aggregates multiple memories into a synthesized narrative, ideal for generating summaries or high-level explanations of complex systems.