/hindsight-docs

OMO (oh-my-openagent)

View Changelog →

Persistent memory for oh-my-openagent (OMO) using Hindsight. Five lifecycle hooks automatically recall relevant context before each prompt and retain conversations after each turn — no changes to your OMO workflow required.

Quick Start

💡 Recommended: Hindsight Cloud

Sign up free for a Hindsight Cloud API key — no self-hosting, no local daemon to manage. From the hindsight-integrations/omo/ directory:

# Hooks (global)
mkdir -p ~/.omo/hooks
cp hooks/hooks.json ~/.omo/hooks/hindsight-hooks.json

# Scripts + settings (global)
mkdir -p ~/.omo/plugins/hindsight/scripts
cp -r scripts/ ~/.omo/plugins/hindsight/scripts/
cp settings.json ~/.omo/plugins/hindsight/settings.json

# Rules (per-project — run from your project root)
mkdir -p .omo/rules
cp rules/hindsight-memory.md .omo/rules/hindsight-memory.md

Then set your API key:

export HINDSIGHT_API_TOKEN=hsk_your_key_here

Add env vars to OMO's allowlist in ~/.config/opencode/oh-my-openagent.jsonc:

{
  "mcp_env_allowlist": [
    "HINDSIGHT_API_URL",
    "HINDSIGHT_API_TOKEN",
    "HINDSIGHT_BANK_ID"
  ]
}

Start a new OMO session — memory is live.

Features

• Auto-recall — on every user prompt, queries Hindsight for relevant memories and injects them as additionalContext (invisible to the transcript, visible to OMO)
• Auto-retain — after each OMO response and sub-agent stop, stores the conversation transcript to Hindsight for future recall
• Sub-agent capture — SubagentStop hook captures learnings from OMO's delegated sub-agents (Claude Code, Codex, OpenCode)
• Dynamic bank IDs — supports per-project memory isolation based on the working directory
• Session-level upsert — uses the session ID as the document ID so re-running the same session updates rather than duplicates stored content
• Cloud-first — defaults to Hindsight Cloud with no local daemon to manage
• Zero dependencies — pure Python stdlib, no pip install required

Architecture

The plugin uses five OMO hook events:

On UserPromptSubmit, the hook reads the prompt, queries Hindsight for the most relevant memories, and outputs a hookSpecificOutput.additionalContext block. OMO prepends this to the conversation before sending it to the model:

<hindsight_memories>
Relevant memories from past conversations...
Current time - 2026-06-08 14:30

- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-06-07)
- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-06-07)
</hindsight_memories>

On Stop and SubagentStop, the hook reads the session transcript, strips previously injected memory tags (to prevent feedback loops), and POSTs the conversation to Hindsight asynchronously.

Connection Modes

1. Hindsight Cloud (recommended)

No setup beyond an API key:

{
  "hindsightApiUrl": "https://api.hindsight.vectorize.io",
  "hindsightApiToken": "hsk_your_token"
}

2. Self-Hosted

Point at your own Hindsight instance:

export HINDSIGHT_API_URL=http://localhost:8888

Or in ~/.hindsight/omo.json:

{
  "hindsightApiUrl": "http://localhost:8888"
}

No API token is required for local instances.

Configuration

Settings are loaded from three sources in order (later wins):

1. Plugin settings.json (cloud URL pre-set)
2. User config (~/.hindsight/omo.json)
3. HINDSIGHT_* environment variables

Connection

Memory Bank

Auto-Recall

Auto-Retain

Debug

Per-Project Memory

To give each project its own isolated memory bank, enable dynamic bank IDs:

{
  "dynamicBankId": true,
  "dynamicBankGranularity": ["agent", "project"]
}

With this config, running OMO in ~/projects/api and ~/projects/frontend stores and recalls memories separately. Bank IDs are derived from the working directory path (e.g. omo::api, omo::frontend).

Multi-Bank Recall

Query additional banks alongside the primary one:

{
  "recallAdditionalBanks": ["shared-team-knowledge"]
}

Troubleshooting

No memories recalled: Recall returns results only after something has been retained. Complete one OMO session first, then start a new one to see memories.

Memory not being stored: retainEveryNTurns defaults to 10 — retain only fires every 10 turns. While testing, add "retainEveryNTurns": 1 to ~/.hindsight/omo.json.

Cloud mode silently skipping: If hindsightApiUrl points to Hindsight Cloud but no hindsightApiToken is set, hooks silently skip. Set HINDSIGHT_API_TOKEN or add it to ~/.hindsight/omo.json.

Debug mode: Add "debug": true to ~/.hindsight/omo.json to see what Hindsight is doing on each turn:

[Hindsight] Recalling from bank 'omo', query length: 42
[Hindsight] Injecting 3 memories
[Hindsight] Retaining to bank 'omo', doc 'sess-abc123', 2 messages, 847 chars