nowledge-mem-opencode-plugin

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.
• 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 installed

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

Setup

Add the plugin to your OpenCode config:

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

Or install globally:

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

Restart OpenCode to load the plugin.

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:

{
  "plugin": ["opencode-nowledge-mem@0.3.4"]
}

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.

How session capture works

Nowledge Mem captures OpenCode sessions in three complementary ways:

1. Background auto-sync (local mode). The desktop app periodically polls OpenCode's session database and imports conversations based on your sync policy. Enable OpenCode in Settings > Thread Sync. No plugin needed for this part.

2. Plugin full session capture. nowledge_mem_save_thread reads the current session's messages via OpenCode's SDK and posts them to Nowledge Mem's thread API. Idempotent (safe to call multiple times) and handles large sessions via HTTP, not shell arguments. Works in both local and remote mode.

3. Plugin proactive knowledge save. nowledge_mem_save captures individual decisions and insights as they happen. nowledge_mem_save_handoff creates a curated summary at wrap-up.

Remote mode note: Background auto-sync (1) reads OpenCode's local SQLite database, so it only works when both tools run on the same machine. The plugin tools (2, 3) work in both local and remote mode.

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.

Hooks

The plugin uses two OpenCode hooks:

• System prompt injection (experimental.chat.system.transform): teaches the agent when to read Context Bundle, use Working Memory fallback, search proactively, and save autonomously. Active on every turn.
• Compaction resilience (experimental.session.compacting): injects a reminder to restore Nowledge Mem context after long sessions trigger context compaction. Ensures the agent doesn't lose awareness of your knowledge tools.

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

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.

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 host-id aliases. Context Bundle will use the stable identity while keeping source_app=opencode for provenance.

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.

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.
• Plugin not loading. Confirm "opencode-nowledge-mem" appears in your opencode.json plugin array. Restart OpenCode after changes.

Links

• OpenCode integration guide
• Documentation
• Discord
• GitHub

---

Made with care by Nowledge Labs