The Memento Protocol

Persistent memory for AI agents.

AI agents have anterograde amnesia — every session starts blank. The Memento Protocol gives agents a structured way to remember, not by recording everything, but by writing instructions to their future selves. Memories decay, consolidate, and evolve — like biological memory, not a log file.

Get Started

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

Verify the install:

npm run test:smoke

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

Step 1: Sign up

curl -X POST https://memento-api.myrakrusemark.workers.dev/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"workspace": "my-project"}'

No email, no password, no OAuth. One curl, one key. Optionally include "email" for account recovery later.

Save the api_key from the response — you'll need it next.

Step 2: Configure your MCP client

Claude Code (project-level): Create .mcp.json in your project root.

Claude Code (global): Add to ~/.claude.json under "mcpServers".

Claude Desktop: Add to your claude_desktop_config.json.

{
  "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"
      }
    }
  }
}

Tip: Replace the path with the actual absolute path to src/index.js in your clone. Run echo "$(pwd)/src/index.js" from inside the repo to get it.

Step 3: Restart your client

The MCP server connects at startup. Restart so it picks up the new config.

Step 4: First session

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

That's it. The agent reads memory at session start, updates it as it works, and writes instructions for next time.

---

Add to Your CLAUDE.md

Paste this block into your project's CLAUDE.md to teach your agent memory discipline:

## Memory (Memento Protocol)

On session start:
1. `memento_health` — verify connection
2. `memento_item_list` — check active work items and their next actions
3. `memento_recall` with current task context — find relevant past memories

Writing memories:
- Instructions, not logs: "API moved to /v2 — update all calls" not "checked API, got 404"
- Tag generously — tags power recall and consolidation
- Set expiration on time-sensitive facts
- Use `memento_skip_add` for things to actively avoid (with expiry)
- Use `memento_item_create` for structured work tracking with next actions

Before session ends:
- `memento_item_update` with progress on active work (include what was done AND what comes next)
- `memento_store` for new decisions and discoveries
- `memento_skip_add` for things to skip next time

---

Hooks

Hooks automate memory at session boundaries — the agent doesn't need to remember to recall or save. Two production-ready scripts are included in scripts/.

Setup

1. Create a .env file in the repo root (copy from the example):

cp .env.example .env
# Then edit .env with your actual API key and workspace name

The .env file is gitignored. It needs three variables:

MEMENTO_API_KEY=mp_live_your_key_here
MEMENTO_API_URL=https://memento-api.myrakrusemark.workers.dev
MEMENTO_WORKSPACE=my-project

2. Make scripts executable (they should already be, but just in case):

chmod +x scripts/*.sh

3. Register in Claude Code settings — add to .claude/settings.json (project-level) or ~/.claude/settings.json (global):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "command": "/path/to/memento-protocol/scripts/memento-memory-recall.sh",
        "timeout": 5000
      }
    ],
    "PreCompact": [
      {
        "command": "/path/to/memento-protocol/scripts/memento-precompact-distill.sh",
        "timeout": 30000
      }
    ]
  }
}

Replace /path/to/memento-protocol with the actual absolute path to your clone.

memento-memory-recall.sh (UserPromptSubmit)

Fires before every agent response. Sends the user's message to the /v1/context endpoint, which returns relevant memories and skip list warnings.

• Timeout: 5 seconds (3s API call + overhead)
• User sees: "Memento Recall: N memories" in their terminal
• Model sees: Full memory details and skip list warnings as injected context (via additionalContext)
• Short messages: Messages under 10 characters are skipped (greetings, "yes", etc.)

memento-precompact-distill.sh (PreCompact)

Fires before Claude Code compresses the conversation. Parses the full JSONL transcript into readable text, then sends it to /v1/distill which extracts key memories, decisions, and observations — so nothing important is lost to compaction.

• Timeout: 30 seconds (transcript processing is heavier)
• User sees: "Memento Distill: extracted N memories" in their terminal
• Transcript parsing: Uses a dedicated parser script if available at /data/Dropbox/Work/fathom/infrastructure/fathom-mcp/scripts/parse-transcript.sh. Falls back to direct JSONL extraction (works everywhere, just less polished formatting).
• Minimum threshold: Transcripts under 200 characters are skipped.

---

Dashboard

Browse and manage memories visually at hifathom.com/dashboard. Paste your API key and workspace name to connect.

---

Documentation

Full reference docs at hifathom.com/projects/memento:

• Quick Start — 5-minute setup guide
• Core Concepts — memories, working memory, skip lists, identity crystals
• MCP Tools — full tool reference with parameters and examples
• API Reference — REST endpoints, request/response schemas, authentication
• Self-Hosting — deploy your own instance with Cloudflare Workers + Turso

---

Development

npm test              # Run unit + integration tests
npm run lint          # Lint with ESLint
npm run format:check  # Check formatting with Prettier
npm run test:smoke    # Quick smoke test of all tools

License

MIT