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"

� 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]

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