Nowledge Mem for OpenCode

Cross-tool knowledge, accessible in every OpenCode session. Your decisions, procedures, and context travel with you.

Nowledge Mem gives OpenCode access to knowledge from all your other AI tools: insights from Claude Code, Cursor, Codex, Gemini, ChatGPT, and every other environment you work in. One knowledge graph, available everywhere.

What you get

• Start every session informed. The plugin can load your Context Bundle at session start: owner identity, AI Identity, active space, active rules, and Working Memory.
• The agent searches for you. When past context would improve the answer, OpenCode finds it through your knowledge graph without being asked.
• Insights stick around. Key decisions and learnings are saved to Nowledge Mem, ready for any future session in any tool.
• Sessions are captured automatically. When OpenCode goes idle after a turn, the plugin saves the conversation as a searchable Mem thread.
• Resumable handoffs. Save structured session summaries that any future session in any tool can pick up from.

Prerequisites

1. Nowledge Mem desktop app running (or the server accessible on port 14242)
2. nmem CLI on your PATH. In Nowledge Mem go to Settings > Developer Tools > Install CLI, use pip install nmem-cli, or on Arch Linux use yay -S nmem-cli / paru -S nmem-cli
3. OpenCode 2.x installed. This release targets the OpenCode v2 plugin API.

nmem status        # Nowledge Mem is running
opencode --version # OpenCode is available

Setup

Add the plugin to your OpenCode config:

{
  "plugins": ["opencode-nowledge-mem"]
}

Or install globally:

{
  "plugins": ["opencode-nowledge-mem"]
}

Restart OpenCode to load the plugin.

OpenCode 1.x

Version 0.4.0 and newer require OpenCode 2.x. On OpenCode 1.x, pin the last v1-compatible release with the v1 plugin key:

{
  "plugin": ["[email protected]"]
}

Verify

Start a new OpenCode session and ask:

What was I working on recently?

OpenCode should call nowledge_mem_context_bundle when full startup context matters, or nowledge_mem_working_memory as the lightweight fallback, then return your current context. If Mem is not running, you will see a connection error in the tool output.

Update

The plugin follows OpenCode's standard plugin update mechanism. To pin a specific version:

{
  "plugins": ["[email protected]"]
}

Tools

| Tool | What it does | |------|-------------| | nowledge_mem_context_bundle | Read startup context: owner identity, AI Identity, active space, active rules, Working Memory, and KFS paths. | | nowledge_mem_working_memory | Read today's Working Memory: focus areas, priorities, recent activity. | | nowledge_mem_search | Search knowledge from all your tools. Supports label, date, and deep mode filters. | | nowledge_mem_save | Save a decision, insight, or preference so any tool can find it. | | nowledge_mem_update | Update an existing memory with refined information. | | nowledge_mem_thread_search | Search past conversations from any tool. | | nowledge_mem_save_thread | Save the current session as a full conversation thread (SDK extraction + HTTP). | | nowledge_mem_save_handoff | Save a curated handoff summary (lighter, agent-composed). | | nowledge_mem_status | Check Nowledge Mem server connectivity and diagnostics. |

Tools that read, write, or save scoped knowledge accept optional space and space_id arguments for one-call routing. Use space_id when you have checked nmem --json spaces list; otherwise pass the exact Space name as space. Explicit tool arguments override NMEM_SPACE and the shared client config for that call.

How session capture works

Nowledge Mem captures OpenCode sessions in four complementary ways:

1. Plugin automatic live capture. When OpenCode reports session.status=idle (or the older session.idle event), the plugin waits briefly for messages to flush, reads the current session through OpenCode's SDK, and creates or appends the matching opencode-<sessionID> thread in Nowledge Mem. This works in local and remote mode because the plugin runs where OpenCode owns the session.

2. Pre-compaction flush. Before OpenCode compacts a long session, the plugin saves the current transcript through the same thread path. The normal context hook restores the Nowledge Mem guidance on the next agent-loop request.

3. Manual full session capture. nowledge_mem_save_thread uses the same capture path on demand. It is idempotent (safe to call multiple times) and handles large sessions via HTTP, not shell arguments.

4. Plugin proactive knowledge save. nowledge_mem_save captures individual decisions and insights as they happen, stamped with source=opencode. nowledge_mem_save_handoff creates a curated summary at wrap-up.

Desktop backfill note: The desktop app can still import OpenCode sessions from the local session database in Threads > Import. That is a historical/backfill path, not the only live-capture path.

Remote mode note: Desktop database polling reads files on the Mem server machine. Plugin automatic capture and nmem t sync run on the machine where OpenCode stores the session, then upload to the configured local or remote Mem server.

To backfill older OpenCode sessions, preview first:

nmem t sync --from opencode --all-projects --limit 20

Then import:

nmem t sync --from opencode --all-projects --apply

Use -p /path/to/project instead of --all-projects when you only want one project. The command reads OpenCode's local session database or legacy JSON storage and writes to the Mem server configured in nmem. Historical imports are marked searchable immediately and leave expensive distillation for an explicit review path.

Hooks

The plugin uses three OpenCode v2 extension points:

• System prompt injection (session.hook("context")): teaches the agent when to read Context Bundle, use Working Memory fallback, search proactively, and save autonomously. Active on every agent-loop request.
• Session event capture (event.subscribe()): listens for session.status=idle and legacy session.idle on the v2 event stream, debounces briefly, then saves the current session as a Mem thread with stable dedupe metadata.
• Compaction resilience (session.hook("compaction")): flushes the current transcript before compaction. The context hook restores Nowledge Mem guidance on the next agent-loop request, instead of adding instructions to the compaction model call.

For project-specific behavioral guidance, add to your AGENTS.md or OpenCode instructions. The included AGENTS.md in this package serves as a reference.

Customize without editing the plugin

OpenCode already gives you a proper instruction layer.

• Shared repo rules: AGENTS.md
• Personal global rules: ~/.config/opencode/AGENTS.md
• Reusable extra files: list them in opencode.json instructions
• Do not edit the installed plugin bundle directly

Treat the package AGENTS.md as reference text and keep your real overrides in OpenCode's own instruction files.

Configuration

No config needed for local use.

| Env Variable | Default | What it does | |-------------|---------|-------------| | NMEM_API_URL | (local) | Remote Nowledge Mem server URL | | NMEM_API_KEY | (none) | API key for remote access | | NMEM_SYNC_TIMEOUT_MS | 120000 | Automatic thread-sync timeout in milliseconds, bounded between 1 second and 30 minutes |

The plugin also reads ~/.nowledge-mem/config.json (shared with all Nowledge Mem integrations). Environment variables take priority.

Remote access

{
  "apiUrl": "https://your-server",
  "apiKey": "your-key"
}

That shared config is used by both the nmem command paths and the HTTP session-save path.

See Access Mem Anywhere.

Spaces

Spaces are optional. If one OpenCode process naturally belongs to one project or agent lane, set it once in the shared Mem client config:

{
  "space": "Research Agent"
}

You can also launch OpenCode with an explicit lane:

NMEM_SPACE="Research Agent" opencode

The plugin's Context Bundle, Working Memory, search, save, and full-session thread save paths will follow that lane. Environment variables take priority over the shared config. If you do not have a real ambient lane, stay on Default.

When a single request names another Space, OpenCode can pass space or space_id directly to the relevant nowledge_mem_* tool. The ambient setting remains the default only for calls that do not provide an explicit Space.

For multi-agent orchestrators, set NMEM_AGENT_ID=<agent-slug> per spawned OpenCode worker. Add NMEM_SPACE only when that run should override the AI Identity's default space. NMEM_HOST_AGENT_ID is for advanced external aliases. Context Bundle will use the stable identity while keeping source_app=opencode for provenance. Automatic session checkpoints isolate cursor state by destination lane (API URL, API key, space, and identity) so one process cannot reuse another destination's acknowledged suffix.

Shared spaces, default retrieval, and agent guidance still come from Mem's own space profile. OpenCode should pick the lane once, not invent a second plugin-local memory partition.

Beyond the default tools

Use the MCP tools for the day-to-day per-turn loop. For anything beyond that -- including graph and relationship queries -- reach for the nmem CLI directly (already installed alongside this plugin). We recommend it whenever you hit a gap in the per-turn tool set:

nmem graph expand <memory-or-crystal-id> --depth 2
nmem graph evolves <memory-id>

Run nmem --help (and nmem graph --help, nmem <command> --help, etc.) to see its full capabilities.

Troubleshooting

• nmem not found. Install with pip install nmem-cli, or on Arch Linux yay -S nmem-cli / paru -S nmem-cli, then run nmem status to verify.
• Server not responding. Start the Nowledge Mem desktop app, or check nmem status for diagnostics.
• Slow automatic thread sync. Thread writes allow 120 seconds by default. If a remote or heavily loaded Mem server needs a different budget, set NMEM_SYNC_TIMEOUT_MS before starting OpenCode. A timeout is not retried immediately because the server may still have completed the write; a later lifecycle sync safely reconciles the transcript through stable message IDs.
• Plugin not loading. Confirm "opencode-nowledge-mem" appears in your opencode.json plugins array on OpenCode 2.x. Restart OpenCode after changes. On OpenCode 1.x, use the v1 plugin key and pin @0.3.10 as shown in Setup.
• OpenCode Desktop sees the package but no tools appear. Fully quit OpenCode Desktop, clear the OpenCode package cache, then restart so it installs the latest package. On Windows the cache is %USERPROFILE%\.cache\opencode; on macOS/Linux it is ~/.cache/opencode.

Links

• OpenCode integration guide
• Documentation
• Discord
• GitHub

Made with care by Nowledge Labs