MCP Write Tools Available in the AI Memory Server

The akitaonrails/ai-memory MCP server exposes 18 distinct write tools that modify wiki pages, manage handoffs, and administer projects, classified by the tool_call_is_write helper function in crates/ai-memory-mcp/src/server.rs.

The Model Context Protocol (MCP) implementation in the akitaonrails/ai-memory repository provides a comprehensive tool surface for managing semantic memory and session data. Unlike read operations that only query state, MCP write tools perform atomic updates, destructive deletions, and multi-step transactions that alter the underlying SQLite store.

How the Server Classifies MCP Write Tools

The server uses negative matching logic to distinguish write operations from read-only queries. In crates/ai-memory-mcp/src/server.rs, the tool_call_is_write function returns true for any tool not explicitly listed in its matches! block:

fn tool_call_is_write(tool: &str) -> bool {
    !matches!(
        tool,
        "memory_query"
        | "memory_read_page"
        | "memory_read_session_observations"
        | "memory_recent"
        | "memory_briefing"
        | "memory_explore"
        | "memory_status"
        | "memory_install_self_routing"
    )
}

All tools not matching these eight read operations are automatically treated as write tools. When this function returns true, the server increments the write counter in per-client activity statistics and enforces write-specific authorization rules.

Complete List of MCP Write Tools

The following 18 tools are registered with the ToolRouter and classified as write operations:

Content Management

• memory_write_page – Atomically creates or replaces a wiki page with new content and tier metadata.
• memory_rename_page – Changes the path or identifier of an existing page.
• memory_delete_page – Permanently removes a page from the store.
• memory_set_page – Updates page metadata including tier classification (e.g., Semantic) and visibility.
• memory_import_page – Imports content from external sources such as Git repositories.

Handoff Lifecycle

• memory_handoff_begin – Initiates a multi-step ownership transfer between users.
• memory_handoff_accept – Completes a pending handoff by taking ownership.
• memory_handoff_cancel – Aborts a pending handoff before acceptance.

Observation Management

• memory_add_observation – Appends a new observation to a session record.
• memory_update_observation – Modifies an existing observation by its unique ID.
• memory_delete_observation – Removes a specific observation from a session.

Quality and Feedback

• memory_feedback – Records quality signals using FeedbackKind variants such as stale or deprecated.

Project Organization

• memory_set_project – Reassigns a page to a different project.
• memory_set_workspace – Moves a project to a different workspace.

Administrative Operations

• memory_purge_project – Irreversibly deletes a project and all associated data.
• memory_reset – Restores a workspace or project to a clean state.
• memory_restore – Recovers data from a backup snapshot.
• memory_backup – Triggers an online backup of the SQLite store.

Practical Usage Examples

Creating or Replacing a Wiki Page

The memory_write_page tool performs atomic writes with tier specification:

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_write_page",
    "arguments": {
      "path": "notes/example.md",
      "content": "# Example\n\nThis is a new page.",

      "tier": "Semantic"
    }
  }
}

The response includes the newly written page’s SHA hash for content verification.

Managing Resource Handoffs

Initiate ownership transfer with memory_handoff_begin:

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "memory_handoff_begin",
    "arguments": {
      "from": "alice",
      "to": "bob",
      "path": "notes/example.md"
    }
  }
}

This creates a pending handoff record and returns a unique handoff ID.

Recording Quality Feedback

Submit page quality signals using memory_feedback:

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "memory_feedback",
    "arguments": {
      "path": "notes/example.md",
      "signal": "stale",
      "reason": "content out-of-date"
    }
  }
}

The FeedbackKind entry persists and surfaces during subsequent linting operations.

Implementation Details and Source Locations

All MCP write tools are implemented and registered in crates/ai-memory-mcp/src/server.rs. The ToolRouter dispatches these tools and relies on tool_call_is_write for access control decisions.

Key test suites validating write tool behavior include:

• crates/ai-memory-mcp/tests/suite/mcp_stateless_http.rs – Verifies the read/write classification through tools/list enumeration.
• crates/ai-memory-mcp/tests/suite/handoff_admission.rs – Tests the complete handoff lifecycle using memory_handoff_begin, memory_handoff_accept, and memory_handoff_cancel.
• crates/ai-memory-mcp/tests/suite/stress_autoscope.rs – Validates memory_write_page and observation tools under concurrent load.

Summary

• Classification Logic: The tool_call_is_write function identifies write tools by excluding eight specific read-only operations, treating all others as mutating.
• 18 Write Tools: The surface includes content management, handoff workflows, observation editing, feedback recording, and administrative destruction tools.
• Activity Tracking: Write tool invocations increment per-client write counters and trigger authorization checks distinct from read queries.
• Atomic Guarantees: Tools like memory_write_page provide atomic replacements, while handoff tools manage multi-state transactions with explicit cancellation support.

Frequently Asked Questions

How does the AI Memory MCP server determine if a tool is a write operation?

The server uses negative matching in the tool_call_is_write function located in crates/ai-memory-mcp/src/server.rs. Any tool name not explicitly listed in the matches! block—which contains only memory_query, memory_read_page, memory_read_session_observations, memory_recent, memory_briefing, memory_explore, memory_status, and memory_install_self_routing—is automatically classified as a write tool.

What happens when an MCP write tool is invoked?

When a write tool is called, the server increments the write counter in per-client activity statistics and applies write-specific authorization rules. This tracking enables audit logging, rate limiting, and permission enforcement that stricter than read-only operations.

Can handoff transactions be reversed after creation?

Yes, pending handoffs can be cancelled using memory_handoff_cancel before the recipient calls memory_handoff_accept. However, once accepted, ownership transfers are permanent and require a new handoff to reverse. The three-tool workflow (begin, accept, cancel) provides safe multi-step transfers.

Where are new write tools registered in the codebase?

New tools are registered with the ToolRouter in crates/ai-memory-mcp/src/server.rs. To maintain correct classification, developers must add read-only tools to the matches! block in tool_call_is_write; all other tools automatically inherit write classification and associated authorization requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}