Add OpenCode integration — real-time conversation persistence plugin

[geco]

This PR adds an integration guide for using MemPalace with OpenCode via the opencode-mempalace-persistence plugin.

What

• New integrations/opencode/SKILL.md — step-by-step setup for:
  • MemPalace MCP configuration
  • Plugin installation
  • AGENTS.md for memory search instructions
  • Identity configuration

Why

OpenCode is a popular open-source AI coding tool. This integration makes MemPalace available to its users with zero configuration — install the plugin, set up MCP, and every conversation is automatically saved to the palace.

Features documented

The integration covers:

• Real-time sync via chat.message + session.idle hooks (no cron)
• Auto-categorization by wing (developer, creative, emotions, family, consciousness)
• Knowledge Graph extraction (decisions, milestones, problems, preferences)
• Async mining — never blocks the UI

Links

• Plugin repo: https://github.com/geco/opencode-mempalace-persistence
• npm: opencode-mempalace-persistence
• awesome-opencode PR: Add opencode-mempalace-persistence plugin awesome-opencode/awesome-opencode#357

[gemini-code-assist]

Code Review

This pull request introduces documentation for the MemPalace integration with OpenCode, covering its architecture, setup, and features like real-time conversation persistence and Knowledge Graph extraction. The review feedback suggests improving the installation command for Python environment safety, correcting syntax highlighting for a JSON snippet, and fixing the configuration key from 'plugin' to 'plugins'. Additionally, a correction was made to the agent instructions to ensure the 'mempalace_kg_query' tool is used correctly without unsupported parameters to prevent validation errors.

[geco]

Thanks everyone for the reviews. All suggestions have been addressed:

• python3 -m pip → safer pip invocation
• Fixed syntax highlighting on JSON block
• "plugin" → "plugins" (correct OpenCode config key)
• Removed unsupported keywords param from mempalace_kg_query instructions
• Install order: uv first, pip second, per @williamblair333's suggestion
  The plugin is published on npm as opencode-mempalace-persistence@1.0.1 and is running in production. Anything else needed before merge? Happy to make further changes.

[geco]

Also worth noting: @igorls (https://github.com/igorls) reviewed the upstream OpenCode source adapter in #1484, which takes the pull approach for retrospective ingest. My plugin is the push side (real-time capture). They're complementary — install plugin + run mempalace mine --source opencode once for full coverage.
Additionally, empirical data from the MemPalace community shows that model choice significantly affects read-side invocation rates (tested on Cat-9a diagnostics: qwen3.5:4b invokes mempalace_search 87% vs gemma4:e4b at 40%). I'm planning to add a "recommended orchestrator" section to the README and a forced-invocation config flag as a belt-and-suspenders approach.
Happy to sync the documentation with the #1484 adapter once both land.

[williamblair333]

Thanks for this — the hook-based approach (chat.message + session.idle) is the right call over cron. Real-time delta sync with async mining is a clean design.
▎
▎ A few things from running MemPalace in production:
▎
▎ 1. Minimum version requirement
▎ PR #1523 (merged in v3.3.5) fixed critical HNSW corruption in repair --yes that causes link_lists.bin to grow to 100+ GB and OOM the host. Users on <3.3.5 would hit this silently during heavy use. Suggest adding mempalace>=3.3.5 to both install paths:

▎ uv tool install "mempalace>=3.3.5"
▎ python3 -m pip install "mempalace>=3.3.5"
▎
▎ 2. Concurrent mine call protection
▎ If chat.message fires in rapid succession, do mine calls serialize or can they overlap? Concurrent mines against the same palace can corrupt the SQLite FTS5 index. Worth documenting whether the plugin queues calls or relies on MemPalace's own locking.
▎
▎ 3. Wing categorization
▎ Auto-assigning to developer/creative/emotions/family/consciousness is opinionated — users with existing palaces may have different wing structures. Could this be made configurable, or at least noted as an override?
▎
▎ Otherwise LGTM — the async architecture and graceful shutdown fallback are solid.

[geco]

@williamblair333 thanks for the thorough review. I've addressed all three points in v1.1.0:

1. Version pin — Updated all install instructions to mempalace>=3.3.5. The HNSW corruption fix is critical.

2. Concurrent mine protection — Refactored from per-wing parallel exec() calls to a single serialized mine call with a miningLock flag. No more concurrent FTS5 collisions possible.

3. Wing categorization — Removed the hardcoded 5-wing keyword system (categorize(), WING_KEYWORDS, wing subdirectories) entirely. Sessions are now exported flat to /tmp/oc-sessions/ and mined with a single mempalace mine --mode convos call — no --wing, no --extract. The model handles KG management via MCP tools (mempalace_kg_add/kg_query/kg_invalidate), same pattern as the Claude Code integration.

The KG regex extraction was also removed — MemPalace's own mining and the model's MCP tools handle that more reliably.

Plugin is at v1.1.0 on npm and the updated SKILL.md reflects all changes. Let me know if anything else is needed before merge.

[igorls]

Maintainer review (docs-only). This is mainly a trust/policy call for the org rather than a code issue:

The SKILL.md frontmatter install block auto-installs the npm package opencode-mempalace-persistence from github.com/geco (a personal account, not the MemPalace org), and every behavioral guarantee in the doc — turn capture, categorization, KG extraction, verbatim storage — lives in that external, unaudited package. Given MemPalace's privacy/verbatim posture, an official-repo doc that silently installs an unaffiliated package needs maintainer sign-off. At minimum, please add a clear "community / third-party, not maintained by the MemPalace team" disclaimer; ideally the org vets or forks the plugin.

Minor doc fixes: the ```json block in Step 3 starts with a # shell comment (invalid JSON if copy-pasted); and version: 1.1.0 vs the sibling openclaw doc's 3.3.0 is confusing for a doc living in this repo.

One correction to an earlier concern of mine: the "developer / creative / emotions / family / consciousness" buckets are not a design-principle violation — those map to the hall content-type classifier (config.py DEFAULT_TOPIC_WINGS / DEFAULT_HALL_KEYWORDS), which coexists with entity-first wings. It's just loose terminology in the doc (it says "wing" where the code means "hall", and "developer" should be "technical").

[geco]

@igorls thanks for the thorough maintainer review. All points addressed in the latest commit:

1. Community disclaimer - Added a clear banner at the top of the SKILL.md, and the install label now says "(community)". The plugin README also carries the disclaimer.
2. JSON block - Fixed the shell comment inside the JSON code block. It's now valid, copy-paste safe.
3. Version - Changed from 1.1.0 to 3.3.5 to match the openclaw doc convention.
4. Wing vs Hall terminology - Since the plugin v1.1.1 no longer does any hardcoded categorization (sessions are exported flat), I've removed the old 5-category list entirely. The wing/hall confusion no longer applies.
5. Trust concern - The plugin is fully open at github.com/geco/opencode-mempalace-persistence (~120 lines TypeScript, v1.1.1 on npm). Happy to submit it for org audit, and I'm open to transferring the repo to the MemPalace organization if preferred.
   All updated in the latest commit on this branch. Let me know if anything else is needed.

[geco]

@igorls @williamblair333 — bumping this for visibility. The plugin has evolved significantly since May. Here's what changed:
v1.2.0–v1.3.1

1. Added experimental.chat.messages.transform hook — the plugin now forcibly injects identity + relevant MemPalace memories into every prompt. No model discipline required.
2. autoInjectContext config flag — lives in ~/.mempalace/plugin-config.json (NOT in opencode.json, since OpenCode's schema validator rejects unknown keys).
3. AGENTS.md simplified to 2 KG-only steps (Query + Record). Memory search is handled by the plugin, not the model.
4. The SKILL.md in this PR should be updated to reflect all of this. Happy to push the changes once I get the green light.
   Next: v1.4.0 will make autoInjectContext: true the default.
   Would love a review when you have time.

[williamblair333]

Working through the same problem on the Claude Code side — hook-layer injection via UserPromptSubmit rather than model discipline — so this direction is directly relevant to us.

Two things on v1.2.0–v1.3.1:

1. experimental.chat.messages.transform — worth noting stability expectations or an OpenCode version range in the SKILL.md; if the hook changes without notice the doc goes stale.

2. autoInjectContext: true default in v1.4.0 — I'd suggest keeping it opt-in a bit longer. Your Cat-9a numbers (40% invocation on weaker models) indicate injected context isn't always useful, and the token cost adds up on lower-context models.

Happy to review the updated SKILL.md when pushed — just make sure @igorls's community disclaimer stays in.

[geco]

@williamblair333 great points, thank you.
On both:

1. OpenCode version range — I've added a note to the SKILL.md (commit ffa8ce6) specifying that experimental.chat.messages.transform requires OpenCode 1.14+ and noting its stability. If the hook changes in the future, the doc will be updated.
2. autoInjectContext default — fair point on token cost. I'll keep it opt-in and drop the "v1.4.0 default" plan. The recommendation stays but the switch remains manual.
   The SKILL.md now has two new commits (20bb6e8 + ffa8ce6) reflecting the v1.3.1 state — auto-inject as recommended, simplified AGENTS.md, community disclaimer intact per @igorls's request. Would appreciate a final review when you have time.

[williamblair333]

Thanks for the update — working through the two new commits. Everything from my May and June reviews is addressed. A few new things from reading the full SKILL.md:

Bug: anyBins prerequisite check

requires:
  anyBins:
    - mempalace
    - python3

anyBins satisfies if any one binary is present. Python 3 is present everywhere, so this guard never actually checks for mempalace. A fresh user with no MemPalace installed sails through and fails silently at Step 1. Should be allBins (or just list mempalace alone — that's the real gate).

Design note: double MCP round-trip on every response
With autoInjectContext: true the plugin already runs mempalace search before every message. The AGENTS.md then adds a mandatory mempalace_mempalace_kg_query on top. So every single response — including quick code questions — incurs two MCP calls. Worth one sentence noting the latency/token cost on slow hardware or large palaces, so users can make an informed choice.

Design note: KG over-recording guidance
"err on the side of saving it" + "a session with zero KG entries is likely missing important information" is aggressive. Models will record noise, KG quality degrades, and the filter step gets noisier over time. "Record facts you're confident about" is less risky.

No concerns on the MemPalace integration design itself — version pin, serialized mining, flat export, opt-in inject are all correct. The npm package trust call remains @igorls's.

[geco]

@williamblair333 all three points addressed in commit a5fc259:

1. anyBins → allBins — changed to allBins with just mempalace. The guard now correctly requires MemPalace to be installed before the skill is available.
2. Double MCP round-trip — added a performance note just before the AGENTS.md section explaining the two calls and typical latency.
3. KG over-recording — softened to "record facts you are confident about. Prefer quality over quantity." Also synced this language to the plugin's README and shipped as opencode-mempalace-persistence@1.3.2.

Plugin is at v1.3.2 on npm with a fully updated README and the same KG quality guidance.

[williamblair333]

@geco — all three look good.

allBins with just mempalace is the right call — clean gate, no Python false-pass. The performance note on the double round-trip is a transparency win (users can see what's happening and decide whether to pre-warm). "Quality over quantity" is the right framing for KG recording — it aligns with how I think about MemPalace entries generally.

v1.3.2 looks solid. From my side this is ready. Thanks for iterating on it this quickly.

[ccnrussell]

I have been using your fork for a week. It worked out great. Thanks for sharing it. Had to make changes for windows version but I think mempalace isn't windows focused at all.

[igorls]

Thanks for iterating on this. I re-reviewed it during the agent-support merge pass.

This doc/plugin direction is still valuable, especially as the real-time "push" side for OpenCode. I merged the complementary #1484 OpenCode source adapter into codex/agent-support-community-merge, so the next revision here should probably be framed as the plugin/real-time layer that complements the first-party source adapter.

Before merge, I would like this updated for the current tree:

• Reference feat(sources): OpenCode adapter on RFC 002 contract #1484 / mempalace.sources.opencode as the built-in historical ingest path.
• Keep the community/third-party plugin disclaimer prominent in both frontmatter and body.
• Keep auto-injection opt-in, with the performance note for the extra search/KG calls.
• Verify the tool names against the current MCP tool surface; avoid instructions that invent unsupported params.
• Add a small Windows note if there are known plugin changes needed there, since a user reported local Windows adjustments.

Once the doc is synchronized with the landed source adapter and current plugin behavior, this looks like a good candidate for docs/integrations merge.

[geco]

Status update — requesting re-review toward merge. The plugin just went through its biggest evolution (now opencode-mempalace-persistence@2.1.0 on npm), and this PR branch is updated accordingly.

Just pushed here: the section @igorls asked for — the SKILL.md now references mempalace.sources.opencode (#1484) and frames this plugin explicitly as the complementary real-time layer (source adapter = backfill history, plugin = never lose the present).

What changed since the June review round:

• AI checkpoints every 15 messages + pre-compaction emergency save (hooks decide when, model files via MCP)
• Synchronous exit save, per-project wings, mine --extract general, backfill mode
• Robustness from real-world reports: interpreter probing (pipx/uv/PATH), no-timeout mines (no orphaned lock-holders), all spawns shell-free (execFile argv)
• Bundled mempalace-recall skill (question-driven recall protocol, adapted from the official one)
• Housekeeping: community issues/PRs triaged and closed on the plugin repo (Shell injection via user message text in mempalaceSearch geco/opencode-mempalace-persistence#1, fix: prevent shell injection by using execFileSync/execFile instead of execSync/exec geco/opencode-mempalace-persistence#2, VENV_PYTHON path hardcoded for pipx — breaks when installed via uv geco/opencode-mempalace-persistence#3, fix: remove 2-min exec timeout that orphans mine processes geco/opencode-mempalace-persistence#4, fix: dead pipx python path; use native wake-up for context injection geco/opencode-mempalace-persistence#5)

Reviewer checklist status: allBins gate ✓, double round-trip transparency note ✓, KG quality-over-quantity ✓, community disclaimer ✓, #1484 framing ✓ (just pushed).

@williamblair333 @igorls — mind taking another look? Happy to address anything remaining.

[igorls]

Thanks for keeping this going. The framing is the right shape: the source adapter handles backfill, the plugin handles the live side. It isn't mergeable yet, though:

1. Step 3 breaks OpenCode. The key is plugin, not plugins. OpenCode's schema has additionalProperties: false, so the config as written fails validation. Your own README already uses plugin.
2. #1484 hasn't landed. The doc says MemPalace "ships" mempalace.sources.opencode. It doesn't yet. Either wait for #1484 or say "once #1484 merges".
3. The doc describes v1.3, not 2.1.0. It still says flat export, no wings, --mode convos only, and "every turn is saved as a drawer". 2.1.0 has per-project wings, --extract general, checkpoint and pre-compaction prompts, saveInterval, and a backfill env var. Please describe what the pinned version actually does.
4. Verbatim storage. --extract general drops any paragraph the heuristic doesn't classify, and only text parts are exported. That breaks "every word, verbatim". Please use the default exchange extraction for the transcript. The checkpoints are fine as an extra layer on top of that.
5. Capture gap. The checkpoint sync fires 500ms after the user message, which is usually mid-reply. It then advances the cursor past the assistant message, so the rest of that reply is never captured. Please sync on session.idle only, or track completion per message.
6. Exit path. The synchronous exit save can block for 30s per query plus 60s per wing. It overrides the default SIGINT/SIGTERM exit, and it ignores miningLock, so it can start a second mine while one is running. Exit needs to stay fast and never race the lock.
7. Privacy. Transcripts are written world-readable to a fixed /tmp/oc-sessions, and a fixed /tmp/oc-plugin-query.py gets executed. Please use a per-user 0700 directory under ~/.mempalace, or mkdtemp.
8. Windows. The frontmatter lists win32, but the binary is hardcoded to ~/.local/bin/mempalace and the venv lookup to bin/python3. Either resolve the binary from PATH (or an env override), or drop win32 and add the Windows note I asked for.
9. Docs hygiene.
   • Pin the npm version in the doc.
   • Use one tool-name convention (mempalace_mempalace_*) throughout.
   • Link integrations/shared/recall-protocol.md instead of a "CRITICAL / MUST every response" AGENTS.md.
   • Don't tell users to create ~/.config/opencode/AGENTS.md; that overwrites the shared-brain rules.
   • Drop or re-measure the "<500ms" claim. A cold mempalace search took about 20s here.
   • Set version: to the current release.

Open question on our side: does a community npm package belong behind an install block in an official integrations/ skill, or as a website/guide/opencode.md page that links to it clearly as third-party? I lean toward the guide page.

[geco]

Thanks for the thorough review, @igorls — this is exactly the kind of pass this needed. Addressed point by point (doc updated on this branch, plugin fixes landed on main as v2.2.0):

1. plugin key — fixed, my mistake. Also pinned the version (opencode-mempalace-persistence@2.2.0).
2. feat(sources): OpenCode adapter on RFC 002 contract #1484 wording — fixed to "once feat(sources): OpenCode adapter on RFC 002 contract #1484 merges". My bad for writing "ships".
3. Doc describes 2.2.0 now — wings, exchange mining, checkpoints, saveInterval, backfill env, startup mine. Stale v1.x claims removed.
4. Verbatim / exchange — you were right. The miner now uses default exchange extraction (one drawer per pair, verbatim); checkpoints + KG remain the intelligence layer on top. (Trade-off noted: no more auto-typed rooms; accepted for the verbatim guarantee.)
5. Capture gap — real bug, good catch. The message row exists before parts finish streaming, so mid-reply exports truncated replies while the cursor moved on. Fixed two ways: the export skips unfinished assistant messages (finish tracking) and clamps the cursor behind them, and mines now run on idle/exit/startup only — never mid-reply snapshots.
6. Exit path — bounded: 45s total budget, 30s per wing, leftovers covered by the new startup mine. miningLock is deliberately ignored at exit (any async mine dies with the process; the sync mine takes ownership — documented in code).
7. Privacy — moved: exports and helper script now live under ~/.mempalace/oc-sessions/ (0700, files 0600). No more world-readable /tmp artifacts.
8. Windows — binary now resolves from PATH (MEMPALACE_BIN override), win32 dropped from frontmatter, Windows note added (untested, reports welcome).
9. Hygiene — version pinned, single mempalace_mempalace_* convention, CRITICAL block replaced with a link to integrations/shared/recall-protocol.md + conditional search, AGENTS.md says append-don't-overwrite, <500ms replaced with an honest cold-start note (~20s first search), version: set to 2.2.0.

On the open question (skill vs guide page): happy either way — a website/guide/opencode.md page linking the plugin as third-party works for me if you prefer it there.

Re-review welcome whenever suits.

[geco]

Small update, no action needed — just keeping the thread accurate while you have bigger fish to fry.

The plugin is now at 2.5.1 on npm (all dogfooded daily). Since my last note: TUI toasts for mines, checkpoints and MCP calls (opt-out), a read-only /memory-log over a structured interaction log, SIGHUP-safe exit saves, backoff retries so two concurrent instances interleave instead of starving, and remaining-to-mine counts on completion.

The SKILL.md on this branch describes the 2.2.0 behavior; I'll sync it to latest whenever you signal the direction is still good — didn't want to churn the branch on every release.

@igorls @williamblair333 — whenever you have a moment, no rush at all.