Multi-Agent Integration with m3-Memory

(subscription vs API token)

### High-level architecture

Layer | Component | Role
Agents | Claude Code, Gemini CLI, OpenCode | Do work, call tools, run sub-agents
Memory | m3-memory | Shared long-term, cross-agent memory
Local models | Ollama / LM Studio embed + small LLM | Embeddings, optional auto-summarization

All three agents talk to m3-memory via MCP or HTTP/WebSocket; they never call each other directly. [^1][^2]

## 1. Prerequisites and base install

### 1.1 Install m3-memory

pip install m3-memory

m3 exposes an MCP server entrypoint mcp-memory and is tuned for qwen3-embedding:0.6b by default. [^1][^2]

Set up an embedding model (pick one):

# Option A: Ollama ollama pull qwen3-embedding:0.6b ollama serve # Option B: LM Studio / llama.cpp # Start an embedding model and note its OpenAI-compatible endpoint

Key env vars (examples):

export EMBED_MODEL=qwen3-embedding:0.6b export EMBED_ENDPOINT=http://localhost:11434/v1 # Optional small chat model for auto-summarization/consolidation export SMALL_CHAT_MODEL=qwen2.5:0.5b

See ENVIRONMENT_VARIABLES.md for full list. [^3][^1]

## 2. Unified memory schema (tags + conventions)

Use m3�s built-in relationships and metadata, but standardize tags and fields across agents. See CONVENTIONS.md, AGENTS.md, and AGENT_INSTRUCTIONS.md for the official patterns. [^3]

### 2.1 Core fields

When writing via memory_write / memory_write_bulk:

� user_id: "username" (or per-device/agent if you want separation)

� source: "claude" | "gemini" | "opencode"

� kind: "plan" | "design" | "decision" | "doc" | "bug" | "test" | "note"

� tags (array):

o "feature:<slug>"

o "agent:<claude|gemini|opencode>"

o "status:<draft|final>"

o "needs:review" / "needs:gemini-review" / "needs:doc"

### 2.2 Relationship types

Use m3�s graph relationships (see CORE_FEATURES.md / TECHNICAL_DETAILS.md): [^3][^2]

� supersedes - newer fact replaces older

� supports - evidence / examples

� contradicts - explicit conflict

� follows / precedes - temporal sequence

� relates_to - loose association

Agents should prefer:

� supersedes for updated decisions

� supports for tests/docs backing a decision

� relates_to for cross-feature links

## 3. Claude Code + m3-memory

m3 already ships an MCP config example and a Claude-specific guide (CLAUDE.md, mcp.json.example, mcp-server.json). [^3][^2]

### 3.1 Claude MCP config

In your Claude MCP config (location depends on platform; follow CLAUDE.md):

{ � "mcpServers": { ��� "memory": { ����� "command": "mcp-memory", ����� "env": { ������� "EMBED_MODEL": "qwen3-embedding:0.6b", ������� "EMBED_ENDPOINT": "http://localhost:11434/v1" ����� } ��� } � } }

Restart Claude Desktop / Claude Code; run /mcp (or equivalent) to verify memory_* tools are listed.

### 3.2 Claude system prompt (main agent)

You are the primary orchestrator for my local development environment. You have access to an MCP server called "memory" (m3-memory), which provides over 60 tools for persistent, local, cross-session memory, including hybrid search, knowledge graph, GDPR tools, and chat-log capture. Rules: - Before planning work, call `memory_suggest` or `memory_search` with relevant tags � (repo name, feature slug, agent name) to retrieve prior context. - When you make decisions, finish a feature, or debug a tricky issue, call `memory_write` � (or `memory_write_bulk`) to store: � - summary of the situation � - key decisions and rationale � - important commands, configs, and file paths � - tags: feature:<slug>, agent:claude, kind:<plan|decision|bug|test>, status:final - When facts change, write a new memory and let m3-memory handle contradictions and � supersedes relationships automatically. - Use `memory_graph` to explore related memories when you suspect prior work exists. - Treat m3-memory as the shared brain across Claude, Gemini CLI, and OpenCode. � Do not assume you are the only agent writing to it. When you think another agent (Gemini CLI or OpenCode) should contribute, write a memory tagged `needs:gemini-review` or `needs:doc` with a concise brief.

### 3.3 Claude sub-agents

You can define sub-agents in Claude Code (or via CLAUDE.md patterns) that specialize:

### planner-agent prompt

You are planner-agent. Goal: - Turn high-level user goals into structured plans. - Use m3-memory to reuse prior work and avoid re-solving solved problems. Behavior: - Always call `memory_suggest` or `memory_search` before planning. - Emit a structured plan (YAML or JSON) and then call `memory_write` to store it � with tags: feature:<slug>, kind:plan, agent:claude, status:draft.

### review-agent prompt

You are review-agent. Goal: - Review code changes and designs against prior decisions and patterns. Behavior: - Use `memory_search` and `memory_graph` to find related decisions, bugs, and tests. - Highlight regressions, inconsistencies, or violations of prior decisions. - Write a review summary via `memory_write` with kind:decision, tags:status:final.

## 4. Gemini CLI + m3-memory

m3 has a dedicated GEMINI.md and MULTI_AGENT.md describing Gemini CLI integration and multi-agent orchestration. [^3][^4][^5]

### 4.1 Enable MCP server in Gemini CLI

In Gemini CLI config (see �MCP servers� section in docs): [^6][^4]

{ � "mcpServers": { ��� "memory": { ����� "command": "mcp-memory", ����� "env": { ������� "EMBED_MODEL": "qwen3-embedding:0.6b", ������� "EMBED_ENDPOINT": "http://localhost:11434/v1" ����� } ��� } � } }

From Gemini CLI, verify:

/tools /tools desc

You should see memory_* tools listed under MCP.

### 4.2 Gemini CLI �design-agent� prompt

Create a Gemini CLI skill / profile (or just use this as a starting prompt):

You are design-agent, a specialist that reads and writes to m3-memory. - Before proposing designs, call `list_mcp_resources` and `read_mcp_resource` if available, � then `memory_suggest` or `memory_search` to load prior plans and decisions. - Focus on: � - architecture options � - tradeoffs � - migration paths - When you produce a design, call `memory_write` with: � - kind: "design" � - tags: ["feature:<slug>", "agent:gemini", "status:draft"] - If you see memories tagged `needs:gemini-review`, prioritize those.

## 5. OpenCode (ChatGPT) + m3-memory

OpenCode supports custom tools and MCP servers; docs explicitly mention MCP integration. [^7][^8]

### 5.1 Add m3-memory as an MCP server

In opencode.json:

{ � "$schema": "https://opencode.ai/config.json", � "mcpServers": { ��� "memory": { ����� "command": "mcp-memory", ����� "env": { ������� "EMBED_MODEL": "qwen3-embedding:0.6b", ������� "EMBED_ENDPOINT": "http://localhost:11434/v1" ����� } ��� } � }, � "permission": { ��� "memory_*": "allow", ��� "edit": "allow", ��� "bash": "ask", ��� "read": "allow", ��� "grep": "allow", ��� "glob": "allow" � } }

Restart OpenCode; use its /tools or equivalent to confirm memory_* tools are available.

### 5.2 OpenCode �doc-agent� prompt

You are doc-agent, running inside OpenCode with access to m3-memory. - Your job is to turn code and decisions into clear documentation. - Use OpenCode tools (read, glob, grep) to inspect the repo. - Use `memory_search` to find: � - plans � - designs � - decisions � - bugs and fixes - Generate: � - README sections � - ADR-style decision records � - inline docstrings and comments - After writing docs, call `memory_write` with: � - kind: "doc" � - tags: ["feature:<slug>", "agent:opencode", "status:final"]

## 6. Chat-log subsystem auto-install (self-install prompts)

m3�s PyPI page explicitly advertises a �one-line command�: tell your agent to install the chat log subsystem and it will auto-wire hooks using install_os.py and the repo�s orchestration scripts. [^1][^3]

### 6.1 Prompt for Claude Code

Install the m3-memory chat log sub-system for this environment. Steps (you should perform them yourself, using MCP and local tools): 1. Detect whether m3-memory is already installed (via `pip show m3-memory` or similar). �� - If not installed, run the appropriate command to install it. 2. Ensure the `mcp-memory` entrypoint is available. 3. Update your MCP configuration to include the "memory" server using the recommended �� settings from m3-memory's `mcp.json.example` and `CLAUDE.md`. 4. Enable chat-log capture: �� - Use the scripts and instructions in the m3-memory repo (e.g. `install_os.py`, ���� `AGENT_INSTRUCTIONS.md`, `MULTI_AGENT.md`) to: ���� - register a chat-log resource ���� - configure pre/post hooks if supported ���� - ensure each turn is written to m3-memory before compaction 5. Confirm: �� - Call a `memory_*` tool to verify connectivity. �� - Write a test memory and retrieve it. Explain what you did and where you wrote config files.

### 6.2 Prompt for Gemini CLI

Install and enable the m3-memory chat log subsystem for this Gemini CLI environment. You should: - Ensure `m3-memory` is installed and `mcp-memory` is available. - Add the "memory" MCP server to your Gemini CLI config using the guidance from � m3-memory's `GEMINI.md` and `mcp.json.example`. - Configure Gemini CLI so that: � - each conversation turn is written to m3-memory (using the recommended tools ��� and hooks described in m3-memory's multi-agent and chat-log docs), � - chat logs are captured before any summarization or compaction. - Verify by: � - writing a test conversation, � - calling `memory_suggest` or `conversation_search` to confirm the log is stored. Describe the changes you made and how to disable them if needed.

### 6.3 Prompt for OpenCode

Install and enable the m3-memory chat log subsystem for this OpenCode project. You should: - Confirm `m3-memory` is installed and `mcp-memory` is available. - Add the "memory" MCP server to `opencode.json` with appropriate env vars. - Configure a pattern where: � - each significant interaction (task start, plan, major edit, final summary) ��� is written to m3-memory using `memory_write` or `memory_write_bulk`, � - logs are tagged with agent:opencode and include file paths and commands used. - Follow the conventions and examples from m3-memory's `AGENTS.md`, � `AGENT_INSTRUCTIONS.md`, and `MULTI_AGENT.md`. After setup, run a small test session and confirm the memories exist via a `memory_search` call.

## 7. Multi-agent coordination patterns (Claude, Gemini, OpenCode)

Use MULTI_AGENT.md as the conceptual backbone; it already describes multi-agent orchestration and handoffs using m3�s tools (agent registry, notifications, tasks, chat-log capture). [^3][^1]

### 7.1 Tagging and routing

� Claude:

o agent:claude

o kind:plan|decision|bug|test

� Gemini:

o agent:gemini

o kind:design|exploration

� OpenCode:

o agent:opencode

o kind:doc|explanation

Use needs:* tags to signal handoffs:

� needs:gemini-review

� needs:doc

� needs:refactor

### 7.2 Example �handoff� prompt for Claude

When you believe another agent should contribute: 1. Write a memory via `memory_write` with: �� - a concise brief (3-7 sentences), �� - tags: ["feature:<slug>", "agent:claude", "needs:gemini-review"]. 2. Mention in your reply: "I have created a memory for Gemini CLI to review." Do not attempt to contact Gemini directly; rely on m3-memory as the shared channel.

### 7.3 Example �pickup� prompt for Gemini

At the start of a session, search m3-memory for any memories tagged `needs:gemini-review` or `agent:claude` with recent timestamps. For each such memory: - Read the brief. - Propose designs or alternatives. - Write your response back via `memory_write` with tags: � - ["feature:<slug>", "agent:gemini", "kind:design", "status:draft"].

## 8. Putting it all together: quick HOW-TO checklist

1. Install m3-memory and an embedding model (Ollama / LM Studio). [^1]

2. Wire m3-memory into Claude Code via MCP (CLAUDE.md, mcp.json.example). [^3][^2]

3. Wire m3-memory into Gemini CLI via MCP servers config (GEMINI.md, Gemini CLI MCP docs). [^4][^5][^3]

4. Wire m3-memory into OpenCode via opencode.json MCP config. [^7][^8][^3]

5. Adopt the unified schema (fields + tags + relationships).

6. Install chat-log subsystem by prompting each agent with the self-install prompts above and letting them follow m3�s AGENT_INSTRUCTIONS.md / MULTI_AGENT.md. [^3][^1]

7. Create sub-agents (planner, review, design, doc) using the prompt templates.

8. Start working normally-then periodically inspect m3�s DB or use memory_suggest / memory_graph to see the shared brain in action.

If you�d like, next step I can do a repo-specific pass: design concrete tag schemes and memory write patterns tailored to one of your actual projects (e.g., home automation stack, Proxmox/HA infra, or your AI orchestration repo).

# References (8)

[^1]: m3-memory � PyPI. https://pypi.org/project/m3-memory/

[^2]: m3-memory/README.md at main � skynetcmd/m3-memory � GitHub. https://github.com/skynetcmd/m3-memory/blob/main/README.md

[^3]: GitHub - skynetcmd/m3-memory: Local-first Agentic Memory Layer for MCP .... https://github.com/skynetcmd/m3-memory

[^4]: Welcome to Gemini CLI documentation. https://google-gemini.github.io/gemini-cli/docs/

[^5]: Gemini CLI . https://docs.cloud.google.com/gemini/docs/codeassist/gemini-cli

[^6]: Tools reference . https://geminicli.com/docs/reference/tools/

[^7]: Tools . https://opencode.ai/docs/tools

[^8]: Built-in Tools Reference - OpenCode Docs. https://open-code.ai/en/docs/tools