Memento Protocol

The Memento Protocol provides persistent memory for AI agents by letting you write instructions to your future self. It enables memory values to decay, consolidate, and evolve over time, supporting memory-based actions without logging every detail.

How to use

To use the Memento Protocol with your MCP client, configure a local or remote MCP server endpoint and run your client so it can store, recall, and manage memory across sessions.

How to install

Prerequisites: you need Node.js and npm installed on your system.

Then clone the project, install dependencies, and verify tests to ensure everything is ready.

git clone https://github.com/myrakrusemark/memento-protocol.git
cd memento-protocol && npm install

npm run test:smoke

You should see all tools listed and "All smoke tests passed."

## Configuration and usage steps

Step 1 sign up using the API to obtain an API key that authenticates your MCP client.

Step 2 configure your MCP client to connect to the server. You can run the server locally or connect to the remote API. The following example shows a local startup configuration using Node to run the MCP entry point and environment variables to supply authentication and workspace details.

{ "mcpServers": { "memento": { "command": "node", "args": ["/home/you/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" } } } }

## First session

Establish a memory entry, then recall it later in the session. You can store a memory by providing content, type, and optional tags to guide recall later.

memento_health() # verify connection memento_store( content: "API uses /v2 endpoints. Auth is Bearer token in header.", type: "instruction", tags: ["api", "auth"] ) memento_recall(query: "api auth") # find it again

## Tips for effective memory management

Treat memories as instructions for future actions rather than raw logs. Tag memories generously to improve recall, set expirations for time-sensitive facts, and use a skip list to avoid repeating irrelevant items.

Before the session ends, update active work progress, store new decisions, and add any items to skip for the next session.

## Available tools

### memento\_health

Verify connectivity between the MCP client and the Memento server at the start of a session.

### memento\_store

Store a memory item with content, type, and optional tags to guide future recall.

### memento\_recall

Recall memories matching a given query to surface relevant past instructions.

### memento\_item\_list

List active memory items and their next actions for the current workspace.

### memento\_item\_create

Create a structured work item to track progress and plan next steps.

### memento\_item\_update

Update progress on an active work item, including what was done and what comes next.

### memento\_skip\_add

Add or update items to skip in the next session to avoid repetition.

### memento\_memory\_recall.sh

Script triggered before each user prompt to recall relevant memories and skip warnings.

### memento-precompact-distill.sh

Script triggered before conversation compaction to distill key memories and observations.