Destructive MCP Tools in ai-memory: Administrative Operations Reference

The ai-memory repository exposes eleven destructive MCP tools—admin endpoints such as purge-project, delete-workspace, and reset—that modify or delete wiki data and require Admin capability with explicit confirmation flags.

The ai-memory project implements a Memory-Client-Protocol (MCP) interface for managing persistent knowledge stores via HTTP. The destructive MCP tools category includes all administrative endpoints that perform state-changing operations on projects, workspaces, and pages within the SQLite-backed wiki system.

Overview of Destructive MCP Tools

Destructive MCP tools are HTTP POST endpoints mounted under the /admin/* namespace. According to the source code in crates/ai-memory-mcp/src/admin.rs, these operations permanently alter or remove data, distinguishing them from read-only query interfaces.

What Makes a Tool Destructive

A tool is classified as destructive when it performs any of the following actions:

• Permanently deleting projects, workspaces, or individual pages
• Renaming entities that require direct database row updates
• Moving data between scopes or merging workspace hierarchies
• Restoring or resetting system state from backups

Available Destructive MCP Tools

The ai-memory MCP interface provides eleven administrative tools that modify the wiki store. Each requires the Admin capability and explicit confirmation to execute.

Project and Workspace Lifecycle Tools

• admin/purge-project: Completely removes a project and all associated pages, sessions, and observations. Implemented in crates/ai-memory-mcp/src/admin.rs at line 86.
• admin/delete-workspace: Deletes an entire workspace including every project it contains. Found at line 90 of crates/ai-memory-mcp/src/admin.rs.
• admin/merge-workspace: Merges one workspace into another, then deletes the now-empty source workspace. Located at line 92 in crates/ai-memory-mcp/src/admin.rs.

Renaming and Relocation Tools

• admin/rename-project: Updates the database row to rename a project without moving underlying files. See line 87 in crates/ai-memory-mcp/src/admin.rs.
• admin/rename-workspace: Renames a workspace and refreshes scope manifests accordingly. Implemented at line 91 in crates/ai-memory-mcp/src/admin.rs.
• admin/move-project: Copies pages to a destination workspace then purges the source project. Found at line 88 in crates/ai-memory-mcp/src/admin.rs.
• admin/move-session: Updates a session's scope to move it between projects or workspaces. Located at line 89 in crates/ai-memory-mcp/src/admin.rs.

Page-Level and System Operations

• admin/delete-page: Permanently deletes a single wiki page by its path. Implemented at line 93 in crates/ai-memory-mcp/src/admin.rs.
• admin/restore-page: Restores a single page from a previously created git checkpoint. Found at line 85 in crates/ai-memory-mcp/src/admin.rs.
• admin/reset: Resets the entire server state, dropping all data and re-initializing the system. This legacy privileged endpoint requires Admin rights.
• admin/restore: Restores the entire wiki and SQLite database from a backup tarball, overwriting current state. Implemented alongside the backup handlers in the admin router.

Authentication and Safety Requirements

Every destructive MCP tool enforces strict authorization checks to prevent accidental data loss.

Required Capabilities

All administrative endpoints require the Admin capability (Capability::Admin) as enforced by the auth middleware in crates/ai-memory-mcp/src/auth.rs. The server validates the caller's AuthLevel before executing any state-changing operation.

Confirmation Flags

As documented in AGENTS.md and implemented in admin.rs at line 4086, destructive operations demand explicit confirmation:

• confirm=true: Required parameter for all destructive tools to confirm intent
• force: Used where applicable to bypass additional warnings

Usage Examples

The following examples demonstrate how to invoke destructive MCP tools via HTTP POST requests to the admin router at http://localhost:49374.

Purge an Entire Project

curl -X POST http://localhost:49374/admin/purge-project \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"workspace":"my_ws","project":"old_project","confirm":true}'

Rename a Project

curl -X POST http://localhost:49374/admin/rename-project \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"workspace":"my_ws","project":"old_name","new_name":"new_name","confirm":true}'

Move a Project Between Workspaces

curl -X POST http://localhost:49374/admin/move-project \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"src_workspace":"ws1","src_project":"proj","dst_workspace":"ws2","confirm":true}'

Delete a Specific Page

curl -X POST http://localhost:49374/admin/delete-page \
     -H "Authorization: Bearer <admin-token>" \
     -d '{"workspace":"my_ws","project":"my_proj","path":"notes/todo.md","confirm":true}'

Implementation in the Source Code

The destructive MCP tools are implemented across several key files in the ai-memory codebase.

Admin Router and Handlers

All destructive routes are defined in crates/ai-memory-mcp/src/admin.rs. This file contains the request handlers for every administrative operation, with specific implementations ranging from line 85 (admin/restore-page) through line 93 (admin/delete-page). The comment at line 4086 documents the confirmation policy for destructive operations.

Authorization Layer

The crates/ai-memory-mcp/src/auth.rs module defines the Capability::Admin enum variant and enforces capability-based access control. The server rejects any destructive request lacking proper authorization headers.

Server Integration

The admin router is registered with the main HTTP server in crates/ai-memory-mcp/src/lib.rs, which wires the MCP tools into the API surface. These tools are MCP-only and are not exposed via the standard client-side CLI commands.

Summary

• Destructive MCP tools in ai-memory include eleven administrative endpoints for deleting, renaming, moving, and restoring projects, workspaces, and pages.
• All tools require HTTP POST requests to the /admin/* namespace with Admin capability authorization.
• Every destructive operation mandates confirm=true to prevent accidental data loss, as enforced in admin.rs at line 4086 and documented in AGENTS.md.
• Key implementations reside in crates/ai-memory-mcp/src/admin.rs with specific handlers at lines 85-93.
• These tools are exclusively available through the MCP interface, not the standard CLI.

Frequently Asked Questions

What is the difference between admin/purge-project and admin/delete-workspace?

admin/purge-project removes a single project and its contents while leaving the workspace intact, whereas admin/delete-workspace recursively deletes the workspace and every project contained within it. Both operations are irreversible without backup restoration, as noted in the destructive operations policy.

How do I authorize a request to use destructive MCP tools in ai-memory?

You must include an Authorization header with a Bearer token that possesses the Admin capability (Capability::Admin). The server validates this against the auth layer defined in crates/ai-memory-mcp/src/auth.rs before processing any destructive request.

Can destructive MCP tools be accessed through the ai-memory CLI?

No. According to the source analysis, these tools are MCP-only endpoints exposed via the HTTP admin router. They are not available through normal client-side CLI commands and must be accessed through direct HTTP POST requests to the MCP interface.

What happens when I call admin/restore-page?

The admin/restore-page tool retrieves a single wiki page from a previously created git checkpoint and restores it to the active wiki state, overwriting any current version of that page. This operation is destructive to existing unsaved changes on that specific page path.

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