docs: add OpenCode + Oh-My-OpenAgent integration guide

[vteran93]

Summary

Adds a complete integration package for OpenCode (https://opencode.ai) users with Oh-My-OpenAgent plugin to set up mempalace as their AI memory system.

Files Added

• examples/opencode_setup.md — Step-by-step guide (follows gemini_cli_setup.md pattern)
• examples/opencode_install.sh — Automated setup script (idempotent, cross-platform)
• examples/agents_md_snippet.md — Copy-paste memory protocol for AGENTS.md

What This Enables

OpenCode users can:

1. Run the install script to get mempalace + MCP configured in one command
2. Follow the guide for manual setup or customization
3. Copy the AGENTS.md snippet to give their AI agents memory protocol instructions

Testing

• All files tested on a real OpenCode + Oh-My-OpenAgent setup
• Install script passes bash -n syntax check (and shellcheck if available)
• Guide config matches OpenCode's McpLocalConfig schema
• MCP server verified with 19 tools via JSON-RPC

[bgauryy]

PR Review: docs: add OpenCode + Oh-My-OpenAgent integration guide

Executive Summary

Aspect	Value
PR Goal	Add integration guide, install script, and AGENTS.md snippet for OpenCode + Oh-My-OpenAgent users
Files Changed	3 (all new)
Risk Level	🟡 MEDIUM — docs-only but contains factual inaccuracies that will break agent workflows
Review Effort	2 — straightforward docs/script, issues are surface-level
Recommendation	🔄 REQUEST_CHANGES

Affected Areas: examples/agents_md_snippet.md, examples/opencode_install.sh, examples/opencode_setup.md

Business Impact: Users following these docs will encounter broken tool calls (6 phantom MCP tools) and incorrect tool references, eroding trust in the integration guide.

Flow Changes: None — no production code modified.

Ratings

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

PR Health

• Has clear description
• References ticket/issue (if applicable) — N/A
• Appropriate size (or justified if large)
• Has relevant tests (if applicable) — N/A for docs

High Priority Issues

(Must fix before merge)

🐛 #1: Phantom tool names in AGENTS.md snippet — 6 tools don't exist, 1 real tool omitted

Location: examples/agents_md_snippet.md:28-31 | Confidence: ✅ HIGH

The snippet claims 19 tools and lists 6 that do not exist in mcp_server.py TOOLS dict: mempalace_list_wings, mempalace_list_rooms, mempalace_get_taxonomy, mempalace_check_duplicate, mempalace_get_aaak_spec, mempalace_graph_stats. The real tool mempalace_browse is omitted. Actual count is 14 tools. Agents following this snippet will attempt calls to non-existent tools.

-### 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`

---

🐛 #2: Wrong tool name mempalace_save_memory — does not exist

Location: examples/opencode_setup.md:107,109 | Confidence: ✅ HIGH

mempalace_save_memory is referenced twice in the Usage section but this tool does not exist. The correct tool for storing content is mempalace_add_drawer.

-- *"Save what we decided about the API structure"* → `mempalace_save_memory`
+- *"Save what we decided about the API structure"* → `mempalace_add_drawer`

Also update the Memory Protocol section (line ~87):

-- Save after significant work: `mempalace_save_memory` with context and key findings
+- Save after significant work: `mempalace_add_drawer` with wing, room, and verbatim content

---

🐛 #3: Hardcoded python3 in install script instead of detected Python

Location: examples/opencode_install.sh:210 | Confidence: ✅ HIGH

The update_opencode_config() function runs python3 - <<'PY' but the script's own detect_python() carefully resolves python3.12/python3.11/python3.10/python3.9. On systems where python3 is absent or points to Python 2.x/3.8, this breaks — contradicting the script's cross-platform design.

-    python3 - <<'PY' "$CONFIG_FILE" "$RESOLVED_PYTHON"
+    "$DETECTED_PYTHON" - <<'PY' "$CONFIG_FILE" "$RESOLVED_PYTHON"

---

Medium Priority Issues

(Should fix, not blocking)

🎨 #4: Dead case statement in run_mempalace() — all branches identical

Location: examples/opencode_install.sh:181-194 | Confidence: ✅ HIGH

All three branches (uv/pipx/pip) execute the exact same command: "$RESOLVED_PYTHON" -m mempalace "$@". The case statement adds 14 lines of complexity with no behavioral difference.

 run_mempalace() {
-    case "$RUNNER_KIND" in
-        uv)
-            "$RESOLVED_PYTHON" -m mempalace "$@"
-            ;;
-        pipx)
-            "$RESOLVED_PYTHON" -m mempalace "$@"
-            ;;
-        pip)
-            "$RESOLVED_PYTHON" -m mempalace "$@"
-            ;;
-        *)
-            error "Unknown runner kind: $RUNNER_KIND"
-            exit 1
-            ;;
-    esac
+    "$RESOLVED_PYTHON" -m mempalace "$@"
 }

If the intent is future-proofing (e.g. uv tool run mempalace vs direct python), add a comment explaining that.

---

🎨 #5: Shell expansion syntax inside JSON example misleads copy-paste users

Location: examples/opencode_setup.md:56 | Confidence: ⚠️ MED

The JSON config example contains $(uv tool dir) inside a string value. JSON doesn't support shell expansion, so copy-paste results in a broken config. The guide does explain this below the block, but a placeholder would be safer.

-      "command": ["$(uv tool dir)/mempalace/bin/python", "-m", "mempalace.mcp_server"],
+      "command": ["<UV_TOOL_DIR>/mempalace/bin/python", "-m", "mempalace.mcp_server"],

---

Low Priority Issues

(Nice to have)

🔗 #6: PR description references non-existent gemini_cli_setup.md

Location: PR body | Confidence: ✅ HIGH

The PR description says "follows gemini_cli_setup.md pattern" but no such file exists in the repo. Existing examples are mcp_setup.md, convo_import.py, and basic_mining.py. This is in the PR body only — not blocking, but worth correcting for accuracy.

---

Created by Octocode MCP https://octocode.ai 🔍🐙

[vteran93]

Thanks for the thorough review, @bgauryy. I pushed the follow-up fixes in 0388a9e.

Quick clarifications:

• Congratulations Milla #1 was a false positive. I re-verified mempalace/mcp_server.py at current milla-jovovich/mempalace:main, and all 19 tools referenced in the snippet are present in the TOOLS dict, including mempalace_list_wings, mempalace_list_rooms, mempalace_get_taxonomy, mempalace_check_duplicate, mempalace_get_aaak_spec, and mempalace_graph_stats. mempalace_browse does not exist in the codebase.
• Integrating MemPalace with SoulForge's code intelligence system #2 is fixed: mempalace_save_memory references were corrected to mempalace_add_drawer.
• feat: Hermes memory provider integration #3 is fixed: update_opencode_config() now uses "$DETECTED_PYTHON" instead of hardcoded python3.
• Using AAAK as language for agents #4 is fixed: the dead case in run_mempalace() was simplified to the single shared invocation.
• feat: add OpenAI Codex CLI JSONL normalizer #5 is fixed: the JSON example now uses <UV_TOOL_DIR> instead of shell expansion syntax.
• fix: handle Windows file-lock errors in test cleanup #6 was also a false positive: examples/gemini_cli_setup.md does exist in the repo, so that PR description reference is not stale.

I’m also opening a separate docs PR to document a real-world .gitignore / large-binary mining hang that came up while using MemPalace in practice.

[web3guru888]

Useful addition to the integration ecosystem — having step-by-step setup guides for each editor/platform lowers the barrier to adoption. The opencode_install.sh script with colored output, Python version detection, and config file management is well-polished.

The AGENTS.md snippet with the full 19-tool protocol reference is a nice reusable template. Pairs well with the auto-plugin approach in #297.

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