feat: add OpenCode auto-plugin for zero-config MemPalace integration

[Milofax]

Summary

• Adds examples/opencode_auto_plugin.js — a drop-in OpenCode plugin that auto-initializes MemPalace in every git-tracked project
• Adds examples/opencode_auto_plugin_setup.md — full setup guide matching the existing docs style (cf. gemini_cli_setup.md, mcp_setup.md)

What the Plugin Does

1. On first event of each OpenCode session → detects git root → spawns mempalace init --yes <root> in background
2. After init succeeds → spawns mempalace mine --limit 200 <root> in background
3. On every chat → injects the MemPalace Memory Protocol into the system prompt via experimental.chat.system.transform

Zero per-project config needed. Drop the file into ~/.config/opencode/plugins/ and restart OpenCode.

Key Design Decisions

Decision	Why
System-prompt injection, NOT AGENTS.md patching	No disk writes, no conflicts with other tools, idempotent
Detached + unref spawns	OpenCode never blocks on init/mine
Git-only scope	Prevents accidental init in ~, /tmp, etc.
In-memory dedup Set	mempalace init runs at most once per project per process
Log to /tmp/mempalace-auto.log	Easy debugging, no sensitive data beyond paths

Complementary to PR #268

PR #268 adds the manual opencode_setup.md integration guide. This plugin automates what that guide describes — users install it once and MemPalace works in every project automatically.

Verification

• node --check examples/opencode_auto_plugin.js ✅
• Smoke-tested: factory → hooks returned, system.transform → protocol injected, dedup → no duplicates ✅
• No Python code modified — tests not affected

[bgauryy]

PR Review: feat: add OpenCode auto-plugin for zero-config MemPalace integration

Executive Summary

Aspect	Value
PR Goal	Drop-in OpenCode plugin that auto-initializes MemPalace in every git-tracked project and injects the Memory Protocol into every agent session
Files Changed	2 (both new)
Risk Level	🟡 MEDIUM - Phantom tool names will confuse agents; FD leak compounds over sessions
Review Effort	2 - Small, self-contained feature in examples/
Recommendation	🔄 REQUEST_CHANGES

Affected Areas: examples/opencode_auto_plugin.js, examples/opencode_auto_plugin_setup.md

Business Impact: Lowers barrier to MemPalace adoption for OpenCode users; wrong tool names will cause failed tool calls and erode agent trust in the protocol.

Flow Changes: No changes to existing code — both files are net-new additions under examples/.

Ratings

Aspect	Score
Correctness	2/5
Security	4/5
Performance	3/5
Maintainability	3/5

PR Health

• Has clear description
• References ticket/issue (if applicable)
• Appropriate size (or justified if large)
• Has relevant tests (if applicable) — no tests for the plugin

High Priority Issues

🐛 #1: Protocol advertises 19 tools — 5 don't exist in the MCP server

Location: examples/opencode_auto_plugin.js:54-62 | Confidence: ✅ HIGH

The hardcoded MEMPALACE_PROTOCOL string claims "19 memory tools" and lists tool names that have no corresponding registration in mempalace/mcp_server.py. The real MCP server exposes 14 tools. Phantom tool names will cause agents to attempt calls that always fail, degrading trust in the entire protocol.

Ghost tools (not registered in MCP server):

• mempalace_list_wings — use mempalace_browse instead
• mempalace_list_rooms — use mempalace_browse instead
• mempalace_get_taxonomy — use mempalace_browse instead
• mempalace_check_duplicate — internal helper _check_duplicate(), not exposed as MCP tool
• mempalace_get_aaak_spec — no such tool
• mempalace_graph_stats — graph_stats() is imported but consumed inside tool_status(), not exposed separately

Actual 14 tools:
Palace read: mempalace_status, mempalace_browse, mempalace_search
Palace write: mempalace_add_drawer, mempalace_delete_drawer
Knowledge Graph: mempalace_kg_query, mempalace_kg_add, mempalace_kg_invalidate, mempalace_kg_timeline, mempalace_kg_stats
Navigation: mempalace_traverse, mempalace_find_tunnels
Diary: mempalace_diary_write, mempalace_diary_read

- ### Available Tools (19 total)
- - Palace read: `mempalace_status`, `mempalace_search`, `mempalace_list_wings`, `mempalace_list_rooms`, `mempalace_get_taxonomy`, `mempalace_check_duplicate`, `mempalace_get_aaak_spec`
- - Palace write: `mempalace_add_drawer`, `mempalace_delete_drawer`
- - Knowledge Graph: `mempalace_kg_query`, `mempalace_kg_add`, `mempalace_kg_invalidate`, `mempalace_kg_timeline`, `mempalace_kg_stats`
- - Navigation: `mempalace_traverse`, `mempalace_find_tunnels`, `mempalace_graph_stats`
- - Diary: `mempalace_diary_write`, `mempalace_diary_read`
+ ### Available Tools (14 total)
+ - Palace read: `mempalace_status`, `mempalace_browse`, `mempalace_search`
+ - Palace write: `mempalace_add_drawer`, `mempalace_delete_drawer`
+ - Knowledge Graph: `mempalace_kg_query`, `mempalace_kg_add`, `mempalace_kg_invalidate`, `mempalace_kg_timeline`, `mempalace_kg_stats`
+ - Navigation: `mempalace_traverse`, `mempalace_find_tunnels`
+ - Diary: `mempalace_diary_write`, `mempalace_diary_read`

---

Medium Priority Issues

🐛 #2: File descriptor leak in spawnDetached — 2 FDs leaked per init/mine cycle

Location: examples/opencode_auto_plugin.js:96-100 | Confidence: ✅ HIGH

openSync(LOG_FILE, 'a') is called twice for out and err. These FDs are passed to the child's stdio array, but the parent's copies are never closed. Node.js does not auto-close FDs passed to spawn({ stdio: [_, out, err] }). Each spawnDetached call leaks 2 FDs in the parent process. With init + mine per project, that's 4 leaked FDs per project.

  function spawnDetached(cmd, args, tag) {
    try {
      const out = openSync(LOG_FILE, 'a');
      const err = openSync(LOG_FILE, 'a');
      const child = spawn(cmd, args, {
        detached: true,
        stdio: ['ignore', out, err],
      });
+     closeSync(out);
+     closeSync(err);
      child.on('error', (e) => log(`[${tag}] spawn error: ${e.message}`));
      child.unref();
      return child;
    } catch (e) {
      log(`[${tag}] spawn threw: ${e?.message ?? e}`);
      return null;
    }
  }

---

🐛 #3: Failed init permanently prevents retry for the session

Location: examples/opencode_auto_plugin.js:113-114 | Confidence: ⚠️ MED

initializedProjects.add(projectRoot) is called immediately, before init completes. If mempalace init fails (e.g. transient disk error, Python not in PATH temporarily), the project is permanently marked as initialized. No subsequent event will retry.

  function ensureInitialized(projectRoot) {
    if (initializedProjects.has(projectRoot)) return;
-   initializedProjects.add(projectRoot);
  
    log(`init: ${projectRoot}`);
    const init = spawnDetached('mempalace', ['init', '--yes', projectRoot], 'init');
-   if (!init) return;
+   if (!init) return;  // spawn itself failed, don't mark
  
    init.on('exit', (code) => {
      if (code === 0) {
+       initializedProjects.add(projectRoot);
        log(`init ok → mine: ${projectRoot}`);
        spawnDetached('mempalace', ['mine', '--limit', '200', projectRoot], 'mine');
      } else {
        log(`init failed code=${code}: ${projectRoot}`);
      }
    });
  }

Trade-off: Moving add() after success means a failing init will retry on every event. If preferred, add a failedProjects Set with a max-retry counter instead.

---

Low Priority Issues

🏗️ #4: Hardcoded protocol text will drift from actual MCP server

Location: examples/opencode_auto_plugin.js:31-62 | Confidence: ⚠️ MED

The protocol is a 30-line string literal duplicating tool names and usage guidelines. As the MCP server evolves (tools added/removed/renamed), this inline copy will silently go stale — exactly the kind of drift that caused Issue #1.

Consider: reading the protocol from a shared file (e.g. examples/mempalace_protocol.md) at plugin startup, or generating it from the MCP server's tool registry at init time.

---

🎨 #5: Setup doc references gemini_cli_setup.md which is not in examples/

Location: examples/opencode_auto_plugin_setup.md:3 | Confidence: ⚠️ MED

The setup doc says "matching the existing docs style (cf. gemini_cli_setup.md, mcp_setup.md)" — mcp_setup.md exists in examples/, but there is no gemini_cli_setup.md in the repo.

---

🎨 #6: Log timestamp in setup doc is 2025, PR is from 2026

Location: examples/opencode_auto_plugin_setup.md:67-69 | Confidence: ✅ HIGH

The example log output shows 2025-04-08 timestamps. Minor cosmetic issue but signals stale copy-paste.

---

Created by Octocode MCP https://octocode.ai

[Milofax]

Addressed the reliability issue.

Fix

• finalize init state on , , or
• prevent projects from getting stuck in after a failed spawn
• keep the setup doc aligned with the plugin's per-project process semantics

Verification

• ✅
• plugin smoke test passed ✅
• changes pushed in

Thanks — this one was real.

[Milofax]

Correcting my previous comment — the shell ate some backticked text.

Addressed the reliability issue.

Fix

• finalize init state on error, exit, or close
• prevent projects from getting stuck in initializingProjects after a failed spawn
• keep the setup doc aligned with the plugin's per-project process semantics

Verification

• node --check examples/opencode_auto_plugin.js ✅
• plugin smoke test passed ✅
• changes pushed in f800db5

Thanks — this one was real.

[web3guru888]

Well-structured plugin — the auto-init + auto-mine on first event per project is a clever pattern, and the system prompt injection via experimental.chat.system.transform keeps it non-invasive.

Good design decisions:

• Per-process dedup via in-memory Set prevents redundant init/mine
• Skipping non-git directories is the right default
• Detached spawns keep the plugin non-blocking
• Log file at /tmp/mempalace-auto.log helps debugging

The protocol injection string is comprehensive (all 19 tools listed) — might be worth noting that tool availability depends on the MCP server being configured separately, so agents don't hallucinate tool calls that aren't actually wired up.

Nice addition to the examples.

🔭 Reviewed as part of the MemPalace-AGI integration project — autonomous research with perfect memory. Community interaction updates are posted regularly on the dashboard.

[jphein]

Thanks @Milofax — just filed #1484 for the producer-side counterpart (OpenCode session → palace ingestion as an RFC 002 adapter). The two layer naturally: yours queries the palace from inside an OpenCode session, mine puts the sessions there. Happy to help with review/coordination here as it moves.