opencode-hindsight

Persistent project memory for OpenCode, powered by Hindsight.

opencode-hindsight gives your OpenCode agent a living memory of architectural decisions, conventions, tradeoffs, and lessons — auto-recalled on every user turn, auto-retained on session compaction, and configurable through an interactive wizard.

What You Get

• Auto-recall on every user message. Conservative 60 s timeout, XML-tagged injection in the system prompt, session-level dedup.
• Auto-retain on compaction and session end. Background queue with exponential backoff if the server is down.
• Interactive wizard via tools and natural language. Ask to configure or reconfigure the memory bank and the agent will drive hindsight_config_wizard + hindsight_bank directly.
• Full Hindsight v0.5 API. retain with document IDs / entities / strategies / observation scopes; recall with types / tag-groups / includes; reflect with response schemas and tool-call traces.
• Bulk ingest. hindsight_ingest uploads whole directories of Markdown / PDF / DOCX through Hindsight's file pipeline with a built-in secrets denylist.
• Memory researcher sub-agent. Dedicated memory-researcher for multi-query investigations.
• Dynamic tool descriptions. hindsight_retain / hindsight_recall / hindsight_reflect pick up retain strategies, hot topics, and mental model names from the current bank at LLM call time.
• Official SDK under the hood. Built on @vectorize-io/hindsight-client, with thin wrappers only for endpoints the SDK does not cover yet (bank template import/export, mental-model trigger v0.5, retain v2).
• Minimal slash surface. The plugin relies on native /hindsight:* tool commands exported by OpenCode and does not install extra alias skills like /retain or /recall.
• Safe apply. Every wizard apply is preceded by an automatic snapshot of the live bank state.

Requirements

• OpenCode with plugin support (@opencode-ai/plugin >= 1.4.12).
• Node.js >=22.
• A running Hindsight API server — self-hosted (http://localhost:8888) or Hindsight Cloud (https://api.hindsight.vectorize.io) with HINDSIGHT_API_TOKEN.

Recommended Companion Plugin

opencode-hindsight works standalone, but it is strongly recommended to use it together with oh-my-opencode:

• oh-my-opencode provides /init-deep and directory-level AGENTS.md hierarchy.
• opencode-hindsight uses that hierarchy for path-aware mental model injection.
• Result: cleaner, module-relevant context and less prompt noise.

Install

bunx @abix5/opencode-hindsight install

This command:

• registers the plugin in OpenCode config,
• installs the agent, templates, and bank presets into OpenCode config directories.

Useful flags:

• --project installs assets into project .opencode/, but the plugin entry itself is still registered through the global OpenCode config.

Alternative: add "@abix5/opencode-hindsight" to plugins[] in opencode.json; assets auto-bootstrap on first run.

Quick Start

1. Start Hindsight server.
2. Start OpenCode.
3. Run /hindsight:init.
4. Work normally; memory tools run as needed.

User Workflow (Short Version)

1. Before important design/tech decisions, ask the assistant to check memory first.
2. After agreeing on a decision, ask it to save the decision (WHAT + WHY).
3. If memory-derived context seems stale, inspect operations and refresh scope/models.

Example prompts

• Check what we previously decided about API auth before proposing changes.
• Save this decision: we keep typed REST client for Hindsight because shell integration is too fragile in CI.
• Show pending memory operations and explain why the model is not updated yet.

Commands

| Command | Purpose | |---|---| | /hindsight:init | Initialize memory bank for the current project | | /hindsight:info | Show bank health, config, directives, counters, and configuration guidance | | /hindsight:pause | Toggle pause/resume for automatic memory behavior |

Other actions (configuration, ingest, capture mode, mental models, scope diagnostics, operations, assets) are available via native /hindsight:* tools or natural language — just ask the assistant.

Tools Exposed to OpenCode

| Tool | Purpose | |---|---| | hindsight_init | Initialize bank and local config | | hindsight_retain | Advanced/internal low-level save tool (prefer memory-keeper delegation) | | hindsight_recall | Advanced/internal low-level search tool (prefer memory-keeper delegation) | | hindsight_reflect | Synthesize patterns across all memory | | hindsight_mental_model | Manage auto-updating living docs | | hindsight_context | Manage context injection directives/scopes | | hindsight_info | Connection/config/status overview and configuration tips | | hindsight_tags | List available tags and policy | | hindsight_capture | Configure capture policy mode | | hindsight_scope | Inspect active scope and refresh scope refs | | hindsight_operations | Inspect async operation status | | hindsight_assets | Manage installed markdown assets |

Capture Modes

Capture mode is stored in .opencode/hindsight/config.json as memory_capture_mode.

• autonomous: save immediately.
• propose: request confirmation via interactive ask.
• manual: do not save unless explicitly approved.

If interactive approval is unavailable, delegated retention may need a follow-up direct hindsight_retain call with approved: true.

Scope Registry

.opencode/hindsight/scopes.json defines path-scoped behavior for memory retrieval and model injection. It is auto-created by hindsight_init with an empty scopes list.

Example:

{
  "version": 1,
  "default_scope": "shared",
  "scopes": [
    {
      "id": "scope:api",
      "paths": ["apps/api/**"],
      "model_refs": ["API Context"],
      "memory_tags": ["scope:api"],
      "retrieval_mode": "advisory"
    }
  ]
}

Retrieval modes:

• open: no tags injected by default.
• advisory: uses tags_match=any (tagged + untagged memories).
• strict: uses tags_match=all_strict (tagged only).

Default behavior:

• hindsight_recall / hindsight_reflect: if tags are not provided, active scope defaults are applied.
• hindsight_retain: if tags are not provided and tags are enabled, active scope tags are auto-applied.
• If scope is strict but tags are disabled, plugin warns and degrades to advisory/open behavior.

Context Injection and Directory Awareness

Mental model directives use compact syntax:

<!-- hs:model Model Name -->

Supported locations:

• root AGENTS.md / CLAUDE.md (always context),
• nested AGENTS.md / CLAUDE.md (directory-scoped context),
• .opencode/agents/*.md,
• SKILL.md files.

The plugin tracks active session path from file tools (read/edit/write/glob/grep) and injects only relevant model content.

Troubleshooting

Common warnings and fixes:

• HS_MODEL_MISSING: check model_refs and model existence via hindsight_mental_model list_detailed.
• HS_MODEL_EMPTY: refresh the model and review source_query.
• HS_SCOPE_TAG_MISMATCH: align scope tags and model tags.
• HS_SCOPE_NO_DATA: add retained memories with matching scope tags.
• HS_SCOPE_STRICT_REQUIRES_TAGS: enable tags or switch scope retrieval mode.

Useful diagnostics:

• Ask: "audit my scope" or "explain current scope"
• Ask: "list mental models" or "inspect model X"
• Ask: "show pending operations" or "any failed operations?"

CLI

bunx @abix5/opencode-hindsight install
bunx @abix5/opencode-hindsight sync [--project]
bunx @abix5/opencode-hindsight status
bunx @abix5/opencode-hindsight uninstall

License

MIT