opencode-omni-memory-plugin 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 caoool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# OpenCode Omni Memory Plugin
+
+Native, local, Git-friendly long-term memory and project continuity for [OpenCode](https://opencode.ai/).
+
+The package installs a global `omni-memory` skill, a companion plugin, seven slash commands, global memory files, and OpenCode instruction wiring. It keeps durable memory separate from mutable project state such as specifications, roadmaps, progress, findings, decisions, and session handoffs.
+
+Formerly published as `opencode-markdown-memory`; installing this version over an old install migrates it in place.
+
+## Features
+
+- Global cross-project memory
+- Host-specific memory
+- Project-scoped durable memory
+- Branch-aware continuation handoffs
+- Protected project charter and agent-maintained working specification
+- Roadmap, progress, findings, and decision tracking
+- Temporary journals for concurrent sessions
+- Conservative automatic capture at meaningful transitions
+- Self-evolution: user corrections and repeated friction are captured once, then promoted from memory into governing configuration
+- Session bootstrap injected by the companion plugin so memory behavior is in context from turn one
+- Compaction defense: the plugin instructs continuation summaries to carry forward memory pointers and un-persisted decisions
+- Bounded startup injection with detailed retrieval on demand
+- Plain Markdown storage with no external memory service
+- Idempotent installer with update, status, backup, and uninstall support
+
+## How it works
+
+Three layers cooperate:
+
+1. **Instructions** (`opencode.json` `instructions` array) auto-load global memory, project memory, and the project handoff into every request.
+2. **Plugin** (`plugins/omni-memory.js`) injects a compact orientation bootstrap into the first user message of each session (idempotent, marker-guarded) and pushes continuation requirements into the compaction prompt via `experimental.session.compacting`. The plugin cannot write files; it makes behavior consistent, while the skill defines it.
+3. **Skill** (`skills/omni-memory`) holds the full rulebook — orientation, precedence, retention, transitions, concurrency, handoff, archival — and is loaded on demand for substantive work.
+
+## Storage model
+
+Global state:
+
+```text
+~/.config/opencode/memory/
+├── GLOBAL.md                 # Always loaded
+├── HANDOFF.md                # Cross-project continuation, loaded on demand
+├── hosts/<hostname>.md       # Host-specific facts
+└── archive/
+```
+
+Project state is created lazily under the active project:
+
+```text
+.opencode/project/
+├── INDEX.md
+├── MEMORY.md                 # Always loaded
+├── HANDOFF.md                # Always loaded
+├── CHARTER.md
+├── SPEC.md
+├── ROADMAP.md
+├── PROGRESS.md
+├── FINDINGS.md
+├── DECISIONS.md
+├── sessions/                 # Temporary and Git-ignored
+└── archive/<milestone>/
+```
+
+Only global memory, project memory, and project handoff are inserted automatically. Detailed project state is retrieved when relevant, keeping normal startup context small.
+
+## Requirements
+
+- OpenCode
+- Bash
+- Git
+- Node.js
+
+The installer edits strict JSON. If your only global configuration is an `opencode.jsonc` containing comments or trailing commas, follow the manual configuration section before running the installer.
+
+## Install
+
+### Recommended: npm package
+
+The package bundles the installer and all managed files, so no separate clone is required:
+
+```bash
+npx opencode-omni-memory-plugin install
+```
+
+Or install it globally to keep the `update`, `status`, and `uninstall` subcommands handy:
+
+```bash
+npm install -g opencode-omni-memory-plugin
+opencode-omni-memory-plugin install
+```
+
+Then quit and restart OpenCode. The same subcommands documented below (`update`, `status`, `uninstall`) work through the `opencode-omni-memory-plugin` binary.
+
+### Alternative: inspect and clone
+
+```bash
+INSTALL_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/opencode-omni-memory-plugin/repo"
+git clone https://github.com/caoool/opencode-omni-memory-plugin.git "$INSTALL_DIR"
+"$INSTALL_DIR/install.sh" install
+```
+
+Then quit and restart OpenCode.
+
+### One-line bootstrap
+
+This downloads the installer, which clones the repository into the managed data directory before installing:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/caoool/opencode-omni-memory-plugin/main/install.sh | bash -s -- install
+```
+
+Review remote scripts before piping them to a shell if you do not control the source.
+
+### Migrating from opencode-markdown-memory
+
+Run `install` (or `update`) from this repository. The installer:
+
+- Replaces the legacy `skills/markdown-memory` with `skills/omni-memory` (the legacy copy is backed up)
+- Migrates the managed `AGENTS.md` block from the old `opencode-markdown-memory` markers to the new ones in place
+- Leaves all memory data untouched
+
+If your old managed checkout lives at `~/.local/share/opencode-markdown-memory/repo`, point its remote at the renamed repository or re-clone into the new path shown above.
+
+## Update
+
+For the recommended managed checkout:
+
+```bash
+"${XDG_DATA_HOME:-$HOME/.local/share}/opencode-omni-memory-plugin/repo/install.sh" update
+```
+
+If you cloned the repository elsewhere:
+
+```bash
+/path/to/opencode-omni-memory-plugin/install.sh update
+```
+
+The updater performs a fast-forward-only Git update and reinstalls managed files. Existing managed files that differ are backed up under:
+
+```text
+${XDG_DATA_HOME:-$HOME/.local/share}/opencode-omni-memory-plugin/backups/<timestamp>/
+```
+
+User memory files are created only when missing and are never overwritten during updates.
+
+Restart OpenCode after every install or update because configuration, commands, plugins, and skills are loaded at startup.
+
+## Status
+
+```bash
+"${XDG_DATA_HOME:-$HOME/.local/share}/opencode-omni-memory-plugin/repo/install.sh" status
+```
+
+## Uninstall
+
+```bash
+"${XDG_DATA_HOME:-$HOME/.local/share}/opencode-omni-memory-plugin/repo/install.sh" uninstall
+```
+
+Uninstall removes the managed skill, plugin, commands, the managed `AGENTS.md` block, and the three configuration instruction entries. It deliberately preserves:
+
+- `~/.config/opencode/memory/`
+- Every project's `.opencode/project/`
+- The downloaded repository checkout
+
+Delete those manually only if you no longer need the stored memory or updater source.
+
+## Commands
+
+After restarting OpenCode:
+
+```text
+/project-init [full]
+/remember [global|host|project] <fact>
+/recall <query>
+/forget <query>
+/handoff
+/project-status
+/memory-audit [global|project|all]
+```
+
+Natural language works too:
+
+```text
+Remember globally that I prefer pnpm.
+Remember for this project that migrations must be backward compatible.
+Recall what we decided about authentication.
+Prepare a handoff for the next session.
+```
+
+## Automatic behavior
+
+For substantive tasks, the injected bootstrap and installed global instructions tell OpenCode to:
+
+1. Orient silently from memory before acting; verified repository state overrides remembered state.
+2. Load the `omni-memory` skill for the full procedure when work is substantive.
+3. Retrieve charter, spec, roadmap, progress, findings, and decisions only when relevant.
+4. Update project state after material decisions, milestone changes, blockers, or verification results.
+5. Capture user corrections and repeated friction once, in the narrowest correct scope, and promote standing behavior rules out of memory into governing configuration.
+6. Enforce a single writer: only the primary agent writes memory or project state; subagents report candidate lessons instead.
+7. Perform a conservative durable-memory check at task completion.
+
+The skill does not record raw transcripts, logs, secrets, temporary status, or unverified assumptions. The plugin's compaction hook asks the summarizer to carry forward memory pointers and un-persisted state, but it cannot write files; if OpenCode terminates abruptly, meaningful-transition checkpoints and `/handoff` provide best-effort continuity.
+
+## Project initialization
+
+Project state is normally created on the first durable project fact. To initialize explicitly:
+
+```text
+/project-init
+```
+
+This creates `INDEX.md`, `MEMORY.md`, and `HANDOFF.md`.
+
+For the complete project-control structure:
+
+```text
+/project-init full
+```
+
+The initializer preserves existing files. Existing project documentation remains independent; `.opencode/project/INDEX.md` records its relationship to the agent working specification.
+
+## Manual configuration
+
+The installer adds these entries to the global `instructions` array:
+
+```json
+{
+  "instructions": [
+    "~/.config/opencode/memory/GLOBAL.md",
+    ".opencode/project/MEMORY.md",
+    ".opencode/project/HANDOFF.md"
+  ]
+}
+```
+
+If your configuration uses commented JSONC, add those entries manually, temporarily provide a strict `opencode.json`, then rerun the installer. The installer refuses to rewrite commented JSONC because doing so could destroy comments or formatting.
+
+The installer also maintains an idempotent block in `~/.config/opencode/AGENTS.md` between:
+
+```text
+<!-- opencode-omni-memory-plugin:start -->
+<!-- opencode-omni-memory-plugin:end -->
+```
+
+Legacy `opencode-markdown-memory` markers are migrated automatically.
+
+## Custom locations and versions
+
+```bash
+OPENCODE_CONFIG_DIR=/custom/opencode \
+OPENCODE_OMNI_MEMORY_HOME=/custom/data/opencode-omni-memory-plugin \
+OPENCODE_OMNI_MEMORY_REF=main \
+./install.sh install
+```
+
+Environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `OPENCODE_CONFIG_DIR` | Override the OpenCode config directory |
+| `OPENCODE_OMNI_MEMORY_HOME` | Override checkout, backups, and install metadata |
+| `OPENCODE_OMNI_MEMORY_REF` | Select the Git branch/ref used by update |
+| `OPENCODE_OMNI_MEMORY_SOURCE` | Install from a local checkout for development/testing |
+| `OPENCODE_MEMORY_HOSTNAME` | Override the host-memory filename |
+
+## Development test
+
+Install into an isolated temporary home without touching your actual OpenCode configuration:
+
+```bash
+TEST_HOME="$(mktemp -d)"
+HOME="$TEST_HOME" \
+XDG_CONFIG_HOME="$TEST_HOME/.config" \
+XDG_DATA_HOME="$TEST_HOME/.local/share" \
+OPENCODE_OMNI_MEMORY_SOURCE="$PWD" \
+./install.sh install
+```
+
+Then run `status`, `update`, and `uninstall` with the same environment.
+
+The repository also includes an isolated smoke test:
+
+```bash
+./tests/install-smoke.sh
+```

package/VERSION

@@ -0,0 +1 @@
+2.0.0

package/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * npm entry point for opencode-omni-memory-plugin.
+ *
+ * Delegates to the bundled install.sh, which already resolves its own script
+ * directory as the install source (the SCRIPT_DIR branch in prepare_source),
+ * so running from the packaged files installs directly with no git clone.
+ *
+ * Usage: opencode-omni-memory-plugin [install|update|status|uninstall|help]
+ */
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const installer = path.join(__dirname, "..", "install.sh");
+const args = process.argv.slice(2);
+
+const result = spawnSync("bash", [installer, ...args], {
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (result.error) {
+  if (result.error.code === "ENOENT") {
+    console.error(
+      "[opencode-omni-memory-plugin] ERROR: 'bash' was not found on PATH. " +
+        "This installer requires Bash, Git, and Node.js.",
+    );
+  } else {
+    console.error("[opencode-omni-memory-plugin] ERROR:", result.error.message);
+  }
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/commands/forget.md

@@ -0,0 +1,7 @@
+---
+description: Remove or correct matching global, host, or project Markdown memory safely.
+---
+
+Load the `omni-memory` skill and forget or correct the information described by `$ARGUMENTS`.
+
+Search the appropriate active memory and directly relevant archives. Remove only matching information, preserve unrelated entries, reconcile references when necessary, and report the scope and concise result. If the request could erase materially different memories, ask for clarification before editing.

package/commands/handoff.md

@@ -0,0 +1,9 @@
+---
+description: Reconcile project state and write a truthful continuation handoff for the next session.
+---
+
+Load the `omni-memory` skill and perform its full handoff procedure.
+
+Inspect current branch, commit, working-tree changes, active task state, and session journals. Reconcile memory, decisions, working specification, roadmap, progress, and findings before rewriting `HANDOFF.md`. Include completed work, partial changes, checks run, blockers, risks, and exact next actions. Remove only fully reconciled temporary journals. Do not create a Git commit.
+
+Additional context: `$ARGUMENTS`

package/commands/memory-audit.md

@@ -0,0 +1,7 @@
+---
+description: Audit native Markdown memory for scope, duplication, staleness, conflicts, and unsafe content.
+---
+
+Load the `omni-memory` skill and audit the scope requested by `$ARGUMENTS` (`global`, `project`, or `all`; default to the current relevant scopes).
+
+Check scope placement, duplication, provenance, last verification, contradictions, sensitive content, active injection size, stale handoff details, unreconciled session journals, and verified findings that should be promoted. Correct unambiguous issues conservatively and list anything requiring user judgment. Do not commit changes.

package/commands/project-init.md

@@ -0,0 +1,9 @@
+---
+description: Initialize native Markdown memory and project-state files for the current project.
+---
+
+Load the `omni-memory` skill and initialize the current project according to its lazy-bootstrap rules.
+
+Use the Git worktree root, or the OpenCode launch directory outside Git. Preserve existing files and documentation. Create the minimal `INDEX.md`, `MEMORY.md`, and `HANDOFF.md` unless `$ARGUMENTS` requests `full`, in which case also create the charter, working specification, roadmap, progress, findings, and decisions from the skill templates. Add the temporary sessions directory to `.gitignore` without disturbing existing rules.
+
+Arguments: `$ARGUMENTS`

package/commands/project-status.md

@@ -0,0 +1,9 @@
+---
+description: Report current project objective, milestone, progress, blockers, findings, and next actions.
+---
+
+Load the `omni-memory` skill and produce a concise current project-status report.
+
+Orient against current repository state, then read the charter, working specification, roadmap, progress, findings, decisions, handoff, and active session journals that exist. Highlight stale or conflicting state and distinguish verified repository facts from remembered context. Do not modify files unless reconciliation is necessary to correct a proven stale claim.
+
+Focus: `$ARGUMENTS`

package/commands/recall.md

@@ -0,0 +1,7 @@
+---
+description: Retrieve relevant global, host, project, handoff, or archived Markdown memory.
+---
+
+Load the `omni-memory` skill and recall information relevant to `$ARGUMENTS`.
+
+Search active memory first, then task-relevant project state, host memory, global handoff, session journals, and archives as appropriate. Retrieve only relevant material, identify stale or conflicting claims, and verify source-sensitive facts before consequential use.

package/commands/remember.md

@@ -0,0 +1,7 @@
+---
+description: Save a durable fact to global, host, or project Markdown memory.
+---
+
+Load the `omni-memory` skill and retain the durable fact in `$ARGUMENTS`.
+
+Honor an explicit first argument of `global`, `host`, or `project`. Otherwise infer the narrowest safe scope from context and ask only if scope materially changes meaning or privacy. Apply all retention, provenance, consolidation, sensitivity, and active-size rules. Do not store temporary status or unverified assumptions.

package/defaults/memory/GLOBAL.md

@@ -0,0 +1,15 @@
+# Global Memory
+
+Durable preferences and facts that apply across projects. Keep this file concise and current.
+
+## Working Preferences
+
+## Tooling and Environment
+
+## Conventions
+
+- Use native Markdown for long-term agent memory, with automatic retrieval and conservative scope-aware capture.
+- Keep durable project memory separate from mutable charter, specification, roadmap, progress, findings, decisions, and handoff state under `.opencode/project/`.
+- Protect project charters from autonomous goal changes; allow agent working specifications to evolve within the charter and record material decisions.
+
+## Recurring Lessons

package/defaults/memory/HANDOFF.md

@@ -0,0 +1,18 @@
+# Global Handoff
+
+Cross-project and OpenCode-configuration continuation state. Retrieve only when relevant.
+
+- Updated:
+- Current focus: none
+
+## Completed
+
+## Current Changes
+
+## Decisions and Findings
+
+## Verification
+
+## Blockers and Risks
+
+## Exact Next Actions

package/defaults/memory/HOST.md

@@ -0,0 +1,11 @@
+# Host Memory: __HOSTNAME__
+
+Machine-specific facts for this host. Verify consequential details before use.
+
+## Platform
+
+## Tooling
+
+## Paths and Constraints
+
+## Verified Lessons

package/defaults/memory/archive/README.md

@@ -0,0 +1,3 @@
+# Global Memory Archive
+
+Store inactive cross-project detail here. Active global memory should remain concise and current; retrieve archived material only when relevant.