MCP Tools

The agent-facing interface. These tools are what your AI agent calls directly.

The Memento Protocol MCP server exposes tools that map to the SaaS API. Each tool call makes an HTTP request to the Workers endpoint.

Session startup

memento_init

Initialize a workspace.

Verifies workspace exists (auto-creates if needed). No parameters. Run once when setting up a new project.

memento_health

Workspace health report.

No parameters. Returns memory counts (active, expired, consolidated), working memory staleness, skip list count, and access log totals. Run this first at the start of every session.

Long-term memory

memento_store

Store a new long-term memory.

Param	Type	Description
`content`	string	The memory content (required)
`type`	string?	`fact` \| `decision` \| `observation` \| `instruction`
`tags`	string[]?	Tags for categorization and recall filtering
`expires`	string?	ISO date for auto-expiry (e.g. `"2026-06-01"`)

Returns an 8-character memory ID. Content is embedded for semantic search automatically.

memento_recall

Search memories by query.

Param	Type	Description
`query`	string	Search query (required)
`tags`	string[]?	Filter to memories with these tags
`type`	string?	Filter by memory type
`limit`	number?	Max results (default: 10)

Uses hybrid ranking (keyword + semantic). Returns formatted results with scores. Recall before starting any subtask — someone may have already figured it out.

memento_consolidate

Merge overlapping memories into one richer memory.

Param	Type	Description
`source_ids`	string[]	IDs of memories to consolidate — minimum 2 (required)
`content`	string?	Your synthesis (recommended). Omit to auto-generate.
`type`	string?	Type for the new memory (default: most common among sources)
`tags`	string[]?	Additional tags (merged with source tags)

The new memory replaces the originals in recall results. Originals are deactivated, not deleted. Use when recall returns 3+ memories about the same topic.

Working memory items

Structured entries for tracking active work, decisions, skip lists, and more. Use these for orientation at session start — they tell you what's in progress, what's decided, and what to skip.

memento_item_list

List working memory items.

Param	Type	Description
`category`	string?	`active_work` \| `standing_decision` \| `skip_list` \| `waiting_for` \| `session_note`
`status`	string?	`active` \| `paused` \| `completed` \| `archived`
`query`	string?	Search title and content

No filters returns all active items. The primary orientation tool — run at session start after memento_health.

memento_item_create

Create a working memory item.

Param	Type	Description
`category`	string	`active_work` \| `standing_decision` \| `skip_list` \| `waiting_for` \| `session_note` (required)
`title`	string	Item title (required)
`content`	string?	Details and context
`status`	string?	Default: `active`
`priority`	number?	0–10, higher = more important
`tags`	string[]?	Tags for filtering
`next_action`	string?	What to do next — tell future-you exactly

memento_item_update

Update a working memory item (partial update).

Param	Type	Description
`id`	string	Item ID to update (required)
`title`	string?	New title
`content`	string?	New content
`category`	string?	New category
`status`	string?	`active` \| `paused` \| `completed` \| `archived`
`priority`	number?	New priority
`tags`	string[]?	New tags (replaces existing)
`next_action`	string?	Updated next action

Only provided fields change. Update next_action as you make progress — include what was done and what comes next so future-you avoids repeating work.

memento_item_delete

Permanently delete a working memory item.

Param	Type	Description
`id`	string	Item ID to delete (required)

Prefer archiving (status: "archived") over deletion — archived items are hidden from default views but preserved for history. Only delete items created in error or containing incorrect information.

Skip list

memento_skip_add

Add a skip list entry.

Param	Type	Description
`item`	string	What to skip (required)
`reason`	string	Why it should be skipped (required)
`expires`	string	ISO date for expiry — required. Skips are temporary by design; use `memento_item_create` with `category: "skip_list"` for permanent skips.

memento_skip_check

Check a message against the skip list.

Param	Type	Description
`query`	string	The message to check (required)

Returns any matching skip entries with their reasons. Auto-clears expired entries.

Identity

memento_identity

Read the identity crystal.

No parameters. Returns the current first-person prose snapshot of who the agent is, what it cares about, and what persists across sessions. Returns a placeholder with setup instructions if no crystal exists yet.

memento_identity_update

Write or replace the identity crystal.

Param	Type	Description
`crystal`	string	The identity crystal text — first-person prose (required)

Each update is stored as a new snapshot (history is preserved). Write in first person. Earned identity — distilled from real experience — is richer than anything generated from scratch.

Legacy working memory

These tools manage the original markdown-based working memory. For most use cases, prefer the structured item tools above (memento_item_list, memento_item_create, etc.) — they support categories, priorities, next actions, and status tracking.

memento_read

Read working memory as markdown.

Param	Type	Description
`section`	string?	Specific section key (omit for all)

Returns the full working memory document or a single section as markdown.

memento_update

Update a working memory section.

Param	Type	Description
`section`	string	Section key (e.g., `active_work`) (required)
`content`	string	New markdown content (required)

Configuration

{
  "mcpServers": {
    "memento": {
      "command": "node",
      "args": ["/path/to/memento-protocol/src/index.js"],
      "env": {
        "MEMENTO_API_KEY": "mp_live_your_key_here",
        "MEMENTO_API_URL": "https://memento-api.myrakrusemark.workers.dev",
        "MEMENTO_WORKSPACE": "my-project"
      }
    }
  }
}

Environment variables

Variable	Required	Description
`MEMENTO_API_KEY`	Yes	Your API key (`mp_live_...`)
`MEMENTO_API_URL`	Yes	API base URL
`MEMENTO_WORKSPACE`	No	Workspace name (default: `default`)