Agent Connect

Connect AI coding agents to m-notes as a persistent knowledge base. Agent Connect configures your agent to read and write project context via MCP, so knowledge persists across sessions.

Prerequisites

A running m-notes instance (self-hosted or cloud)
An API key (see API Keys)
A workspace ID (found in Settings or the URL bar)
The mnotes CLI installed (see CLI Reference)

Quick Start

Run the connect command from your project root to configure your AI agent:

bash

mnotes connect claude-code \
  --url https://your-instance.mnotes.app \
  --api-key mnk_your_api_key \
  --workspace ws_your_workspace_id

This writes the necessary config files for the target agent. Your agent will automatically discover and use m-notes MCP tools on next launch.

Supported Targets

Target	Config Files	Description
`claude-code`	`.mcp.json + CLAUDE.md`	Configures Claude Code with MCP server and agent instructions for m-notes integration.
`codex`	`.mcp.json + AGENTS.md`	Configures OpenAI Codex with MCP server and agent instructions.
`openclaw`	`instructions.md`	Writes agent instructions to the OpenClaw workspace config directory.

Session Workflow

Once connected, your agent follows a three-phase workflow each session:

1. Session Start — Load Context

The agent loads workspace notes, recent context, and relevant knowledge from m-notes.

bash

# Automatically called when your agent session starts
project_context_load
# Loads workspace notes, recent context, and knowledge graph

2. During Session — Store Knowledge

As the agent works, it stores decisions, patterns, and context back to m-notes using structured keys.

bash

# During your session, the agent stores knowledge automatically
knowledge_store --key "arch/auth" --value "Using NextAuth v5 with JWT strategy"
knowledge_store --key "bug/issue-42" --value "Race condition in folder rename"

3. Session End — Persist Log

A session summary is saved so future sessions have continuity.

bash

# When the session ends, a session log is persisted
session_log --summary "Implemented OAuth flow, fixed 3 bugs"

Key Naming Conventions

Knowledge entries use a prefix-based naming convention to keep context organized and discoverable:

Prefix	Purpose	Example
`arch/`	Architecture decisions and patterns	`arch/auth-strategy`
`pattern/`	Reusable code patterns	`pattern/error-handling`
`bug/`	Bug context and root causes	`bug/issue-42`
`dep/`	Dependency notes and gotchas	`dep/prisma-migrations`
`decision/`	Product or tech decisions	`decision/api-versioning`
`context/`	Project-wide context	`context/deploy-process`

Connection Status

Check whether your agent is properly connected:

bash

mnotes connect --status

This verifies the config files exist, the MCP endpoint is reachable, and the API key is valid.

Troubleshooting

Connection fails

If mnotes connect fails or your agent cannot reach the MCP server:

bash

# Verify your instance is reachable
curl -s https://your-instance.mnotes.app/api/health

# Check your API key is valid
mnotes list --api-key mnk_your_key --url https://your-instance.mnotes.app

# Re-run connect to regenerate config files
mnotes connect claude-code --url ... --api-key ... --workspace ...

MCP tools not available

If your agent starts but cannot see m-notes MCP tools:

bash

# Verify MCP config exists
cat .mcp.json

# Test MCP endpoint directly
curl -X POST https://your-instance.mnotes.app/api/mcp \
  -H "Authorization: Bearer mnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list"}'

Ensure the .mcp.json file is in the project root (not a subdirectory) and that your agent is launched from the same directory.