How to Configure and Utilize the Hindsight Memory System in omp

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. To activate the feature, set memory.backend to "hindsight" in your ~/.omp/config.yml file.

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.

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): 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): Thin wrapper around REST endpoints including /memories, /memories/recall, and /memories/reflect.
• Bank Scoping (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): 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) accepts an array of memory items and enqueues them for asynchronous batch insertion.

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) queries the remote store and returns formatted results.

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. No session state is mutated during recall.

Synthesizing Knowledge with the Reflect Tool

The reflect tool (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.

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

According to 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. 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 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 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 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 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) 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}