@opencode-ai/plugin-claude-memory

Repo-local memory plugin for opencode.

Install

Add the plugin to your opencode config:

{
  "plugin": ["@lansya/opencode-plugin-claude-memory@latest"]
}

opencode will install the package and load its ./server entry.

To summarize each session at most once:

{
  "plugin": [
    [
      "@lansya/opencode-plugin-claude-memory@latest",
      {
        "once": true
      }
    ]
  ]
}

To keep the helper consolidation session for inspection:

{
  "plugin": [
    [
      "@lansya/opencode-plugin-claude-memory@latest",
      {
        "debug": true
      }
    ]
  ]
}

Storage

The plugin stores repo-local memory in:

• .opencode/memory/MEMORY.md
• .opencode/memory/topics/*.md

MEMORY.md is the single source of truth and uses this format:

- (3) [d:2026-05-14] Keep answers terse. [ref:topics/answer-terse.md]
- (2) [d:2026-05-01] Run bun typecheck from the package directory.

Each row carries:

• score in [1..5]
• next decay date as [d:YYYY-MM-DD]
• memory text
• optional [ref:topics/*.md]

There is no hidden runtime score, no graveyard, and no sidecar metadata for public rows.

The plugin also keeps helper runtime state in .opencode/memory/.state.json and budgeted candidate transcript snapshots in .opencode/memory/.pending/.

The state file records whether a session is currently a candidate, running, completed_no_change, completed_updated, or failed, plus attempt timestamps, the helper debug_session_id when retained, and the last error when a consolidation run fails.

These files should be gitignored.

Current Model

• Injects a materialized view of MEMORY.md into system context before model calls.
• Materializes rows lazily to today before injection and before settle/publish.
• Rows lose 1 point per 7-day interval once their [d:...] is due.
• When a row reaches 0, it is removed completely.
• Re-confirming an existing row increases score by 1 up to 5 and resets its next decay date.
• Rewriting an existing row refreshes its next decay date.
• A dormant repository still decays by wall-clock time; stale rows disappear naturally the next time memory is read.
• Truncates the injected memory view to 200 lines / 25KB.
• Uses session.idle to mark the current session as the next consolidation candidate.
• Consolidates the previous candidate when a different session is created or becomes idle.
• Skips candidate tracking for sessions whose first user input contains the stable /dream sentinel.
• Runs consolidation in a helper session with repo read access and edit access limited to .opencode/memory/.work/<run>/OPS.md.
• Helper sessions read .work/<run>/BASE_MEMORY.md and edit only OPS.md.
• BASE_MEMORY.md is a helper snapshot with temporary anchors and scores, but it does not expose decay dates.
• settle() applies ops against the current published MEMORY.md after materializing overdue decay, then republishes MEMORY.md.
• Summary does not edit topics/*.
• Keeps topic files and transcript snapshots off-prompt; the helper reads transcript snapshots on demand with tools.
• Supports once: true to prevent a session from being consolidated more than once.
• Supports debug: true to keep the helper consolidation session instead of deleting it after completion.
• Generates .opencode/commands/dream.md on startup if it is missing.
• /dream is a front-channel command that curates topics/* and fills [ref:topics/*.md] for repo-backed memories.
• If the plugin creates dream.md after the app is already running, restart TUI to load the new command.
• Run /dream in a fresh session as the first user input so the sentinel-based exclusion applies cleanly.

Summary only edits staged .work/<run>/OPS.md files. Topic files are not maintained by summary; they are only curated through /dream.