opencode-hindsight

Persistent project memory for OpenCode, powered by Hindsight.

opencode-hindsight helps your assistant remember architectural decisions, conventions, tradeoffs, and lessons across sessions. It adds native memory tools to OpenCode (no shell wrappers) and injects only relevant memory context into the system prompt.

What You Get

• Recall before decisions (hindsight_recall) so the assistant checks existing context first.
• Structured retention (hindsight_retain) with categories and optional tags.
• Reflective synthesis (hindsight_reflect) across all stored project memory.
• Auto-updating mental models (hindsight_mental_model) for living architecture docs.
• Scope-aware memory defaults via .opencode/hindsight-scopes.json.
• Async operation visibility (hindsight_operations) and scope diagnostics (hindsight_scope).
• Capture policy control (hindsight_capture): autonomous, propose, manual.
• Startup asset reconciliation: plugin-managed commands/skills/agents/templates are auto-synced on launch (install/update/remove obsolete).

Requirements

• OpenCode with plugin support.
• Node.js >=18.
• A running Hindsight API server (default: http://localhost:8888).

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 commands, skills, agent, and templates into OpenCode config directories.

Useful flags:

• --project install into project .opencode/ instead of global 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:status | Show bank health, config, directives, counters, and available actions | | /hindsight:rescan | Explore project and retain key architecture knowledge | | /hindsight:pause | Toggle pause/resume for automatic memory behavior |

Other actions (capture mode, mental models, scope diagnostics, operations, assets) are available via natural language — just ask the assistant.

Tools Exposed to OpenCode

| Tool | Purpose | |---|---| | hindsight_init | Initialize bank and local config | | hindsight_retain | Save project knowledge (WHAT + WHY) | | hindsight_recall | Search past project knowledge | | hindsight_reflect | Synthesize patterns across all memory | | hindsight_mental_model | Manage auto-updating living docs | | hindsight_context | Manage context injection directives/scopes | | hindsight_status | Connection/config/status overview | | 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.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, call hindsight_retain again with approved: true.

Scope Registry (v1)

.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