4.1 OpenCode

This chapter is the on-ramp for using MentisDB inside OpenCode — the open-source terminal-based coding agent. It's written from inside OpenCode itself: every example below was produced by a session that has MentisDB as its memory layer.

What you'll get: a per-project durable memory that survives Ctrl+C, context window resets, and the dozens of little one-shot sessions you start every day. The agent stops asking the same questions, stops re-reading the same files, and starts treating your project like a long-running collaboration instead of a stranger.

Read first: the Operator Playbook is the daily usage manual. This chapter wires OpenCode to MentisDB; the playbook teaches when to prompt for search, when to append, what to skip, and how to make memory compound.

Local vs team memory: local MentisDB is good for learning and solo work. For a team, MentisDB is strongest as a long-running server in the cloud or on your internal network, with every coding harness connecting to the same HTTPS MCP endpoint. That lets OpenCode, Codex, Claude Code, and teammates share durable agentic memory instead of each laptop having an isolated brain.

Prerequisites

OpenCode installed and configured with a model provider
mentisdb binary on your PATH — install with cargo install mentisdb --features server or brew install mentisdb
A project directory you want the agent to remember across sessions

Step 1: Tell the harness to open project memory

Do not start by running imaginary setup commands. In an MCP harness, your normal path is: connect the MentisDB MCP server, then prompt the agent to bootstrap the right chain through the mentisdb_bootstrap, mentisdb_list_chains, and mentisdb_recent_context tools.

Use MentisDB as memory for this repository.

First, list available chains and choose the one that matches this repo.
If no good chain exists, bootstrap one using the repository name as the chain key.
Then read the core MentisDB skill, load recent context, and write a short checkpoint
describing the repo and what we are about to do.

A well-connected OpenCode session should respond by calling MCP tools, not by shelling out to non-existent commands. You should see behavior like this in the transcript:

[calls mentisdb_list_chains]
[calls mentisdb_bootstrap with chain_key="my-repo"]
[reads mentisdb://skill/core or calls mentisdb_skill_md]
[calls mentisdb_recent_context]
[calls mentisdb_append with thought_type="Summary", role="Checkpoint"]

Operator check: if the agent says it initialized memory but you do not see MCP tool calls, stop it and ask it to use the MentisDB MCP tools explicitly. A statement like "I will remember that" is not durable memory.

Step 2: Add MentisDB as an MCP server

OpenCode reads MCP server config from opencode.json or opencode.jsonc at the project root, or from ~/.config/opencode/opencode.json for global config.

For a project-local setup, create or edit opencode.json:

{
  "mcp": {
    "mentisdb": {
      "type": "local",
      "command": ["mentisdb", "--mode", "stdio"]
    }
  }
}

For a global setup, keep the MCP server configuration global, but still make the chain choice in the prompt or in the agent's first mentisdb_bootstrap call. The chain key is a MentisDB tool parameter, not something the user should have to manage with a shell command.

Restart OpenCode. You should see the MCP server come up in the status line and the mentisdb_* tools appear in the tool palette.

Remote / multi-user setup

If you're running mentisdb as a long-lived HTTP server (see 3.5 Deployment Patterns), point OpenCode at it:

{
  "mcp": {
    "mentisdb": {
      "type": "remote",
      "url": "https://mentisdb.example.com/mcp",
      "headers": {
        "Authorization": "Bearer mentisdb_xxxxx"
      }
    }
  }
}

Step 3: Install the MentisDB skill

OpenCode has a skills/ directory where agents look for operating instructions. The MentisDB skill teaches the agent the search-first discipline from chapter 0.4 and lists the available tools and thought types.

# Per-project skill
mkdir -p .opencode/skills
curl -L https://docs.mentisdb.com/mentisdb-skill.md \
  -o .opencode/skills/mentisdb.md

# Global skill (applies to all projects)
mkdir -p ~/.config/opencode/skills
curl -L https://docs.mentisdb.com/mentisdb-skill.md \
  -o ~/.config/opencode/skills/mentisdb.md

The skill file is loaded automatically when an OpenCode session starts and includes the three-question rule, the anti-pattern warnings, and the exact tool names the agent should call.

Step 4: Prime the agent

At the start of any session, paste a concrete operating instruction so the agent knows exactly how to use memory through MCP:

Use MentisDB as your durable memory for this repo.

Before editing:
1. Bootstrap the project chain through MCP.
2. Read the MentisDB core skill.
3. Search for prior decisions, constraints, mistakes, and lessons related to this task.
4. Summarize the relevant memories you found.

After meaningful work:
- Append durable decisions, lessons, mistakes, task completions, and checkpoints.
- Do not append raw logs or duplicate notes.
- Before stopping, write a Summary checkpoint with tests run and next steps.

You only need to paste this once per session. If the agent starts editing before it searches, interrupt it and ask for the memory search first. The improvement comes from retrieval before action, not from saving notes after the fact.

Step 5: A working session

Here's a realistic first session. The user is debugging a flaky test in a Rust project that has been touched by the agent before.

$ opencode

# (primer pasted once)
> Use mentisdb as your memory system for this project. Before
> writing any new thought, search for existing similar memories
> and link to them.

# (real task)
> The test in tests/rate_limit_tests.rs:73 fails about 30% of
> the time. It looks like a timing issue. Can you investigate?

A well-primed agent will, before debugging, search the chain:

> Let me check what we already know about this test and rate
> limiting in this project.

  [calls mcp__mentisdb__mentisdb_recent_context with last_n=10]
  [calls mcp__mentisdb__mentisdb_ranked_search with
   text="rate limit test flaky timing"]

The chain surfaces two relevant prior thoughts:

A Decision from last week: "Throttling at the API gateway is more reliable than per-service limits. We saw 3 incidents where per-service limits failed during deploys."
A Mistake from two weeks ago: "Spent 2 hours on a flaky test that was actually exposing a real race condition in the token bucket. Fixed by adding a 10ms sleep, not by retrying the test."

Armed with this context, the agent's investigation is faster and more accurate. It might say:

> Found two relevant memories. Last week we decided to push
> throttling to the API gateway, and two weeks ago we had a
> similar flake that turned out to be a real race in the token
> bucket. Let me look at the test and the bucket implementation
> together — the flake might be the same kind of issue.

  [reads tests/rate_limit_tests.rs:73]
  [reads src/rate_limiter.rs]
  [identifies actual race condition, not a test bug]

When the agent finds the real fix, it records a new memory with a backlink to the prior mistake:

  [calls mcp__mentisdb__mentisdb_append with
   thought_type="Correction",
   content="The flaky test at tests/rate_limit_tests.rs:73 was \
            the same race condition we hit on May 22. The fix \
            is in src/rate_limiter.rs:142 — the refill loop \
            needs a generation counter to avoid lost updates. \
            The 10ms sleep we added in May was masking it, not \
            fixing it.",
   refs=[42]]  # the prior Mistake thought's index

Next time someone hits a flaky test, the chain has both the symptom, the cause, and the fix, all cross-linked.

Daily workflow patterns

End-of-day checkpoint

At the end of a long session, ask the agent to checkpoint:

> Save a checkpoint of what we did today and what's pending
> for tomorrow.

The agent writes a Summary with role: Checkpoint that captures the day's state. Tomorrow's session starts with mentisdb_recent_context and picks up where you left off.

Cross-session continuity

OpenCode sessions are short by design. To make them feel like one long collaboration, train the agent (and yourself) to:

Always mentisdb_recent_context at session start
Always search before writing
Always checkpoint before ending a session

After a week of this, you'll have a chain dense enough that any new session can answer "what's the state of X?" with a single ranked search.

Multi-agent setups

OpenCode can run with multiple agents in parallel (e.g. a planner and an executor). Give each role a distinct agent_id in the MCP append calls so their memories are attributable. Do this through the harness prompt, not with a separate shell setup step:

For this task, use these MentisDB agent identities:
- planner for decomposition and checkpoints
- executor for code changes and test results
- critic for review findings

When appending memories, set agent_id to the role that actually produced the thought.

Now you can ask "what did the critic object to last time we did this refactor?" and get a clean answer scoped to that agent's perspective.

Production notes

Storage location

By default, mentisdb stores chains under the platform default MENTISDB_DIR root, normally ~/.cloudllm/mentisdb. For Docker, CI, or a cloud server, use a stable data volume:

export MENTISDB_DIR=/var/lib/mentisdb

Backups

Chains are append-only files. Backup is cp -r or rsync. For automated backups, see 3.5 Deployment Patterns.

Embeddings

For better semantic retrieval, manage vector sidecars from MentisDB itself rather than inventing harness-specific environment variables. Start with the default local sidecar, then move to FastEmbed if your deployment was built with local-embeddings.

Ask your agent to inspect managed vector sidecar status through MCP/dashboard tools, or use the dashboard's vector sidecar controls. See 3.1 Embedding Provider Selection and 3.2 Vector Sidecar Management for the actual provider and rebuild model.

Troubleshooting

"The mentisdb_* tools don't appear in OpenCode"

Check the JSON syntax in opencode.json (use opencode.jsonc if you want comments)
Verify mentisdb --help works from the command line first, then check the OpenCode MCP logs for stdio startup errors
Check ~/.config/opencode/logs/ for MCP startup errors
Restart OpenCode — config is read at startup, not hot-reloaded

"The agent appends without searching"

The primer was probably not pasted, or the skill file isn't loading. Check that .opencode/skills/mentisdb.md exists and contains the search-first discipline section. Some OpenCode versions require skill files to have a YAML frontmatter header — see the skill format docs.

"Search returns nothing useful"

Make sure mentisdb_ranked_search is being called with a text parameter, not just filters
Enable RRF reranking: enable_reranking=true in the call
Check min_importance and min_confidence thresholds — they might be filtering good hits
If semantic search seems stale, ask the agent to inspect vector sidecar status through the MCP/dashboard surfaces before guessing

"The chain grows too fast / gets too noisy"

You're hitting the dedup problem. Solutions:

Lower importance on routine Subgoal thoughts (already at 0.4 by default — go to 0.2)
Use scope:session for routine steps that don't need to be shared
Set MENTISDB_DEDUP_THRESHOLD=0.85 to auto-supersede near-duplicates

What you've built

You now have OpenCode as a long-running collaborator with a durable memory. Every session picks up where the last one left off. Every decision, mistake, and lesson is recorded, cross-linked, and retrievable. The agent stops forgetting and starts learning.

The next chapter covers the same setup for Claude Code, which is the most popular CLI coding agent and has a slightly different MCP configuration pattern.