memento-mcp 0.1.0

package/.env.example

@@ -0,0 +1,3 @@
+MEMENTO_API_KEY=mp_live_your_key_here
+MEMENTO_API_URL=https://memento-api.myrakrusemark.workers.dev
+MEMENTO_WORKSPACE=my-project

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Myra Krusemark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# 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
+
+```bash
+git clone https://github.com/myrakrusemark/memento-protocol.git
+cd memento-protocol && npm install
+```
+
+Verify the install:
+
+```bash
+npm run test:smoke
+```
+
+You should see all tools listed and "All smoke tests passed."
+
+### Step 1: Sign up
+
+```bash
+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`.
+
+```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:
+
+```markdown
+## 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):
+
+```bash
+cp .env.example .env
+# Then edit .env with your actual API key and workspace name
+```
+
+The `.env` file is gitignored. It needs three variables:
+
+```bash
+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):
+
+```bash
+chmod +x scripts/*.sh
+```
+
+3. **Register in Claude Code settings** — add to `.claude/settings.json` (project-level) or `~/.claude/settings.json` (global):
+
+```json
+{
+  "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](https://hifathom.com/dashboard). Paste your API key and workspace name to connect.
+
+---
+
+## Documentation
+
+Full reference docs at [hifathom.com/projects/memento](https://hifathom.com/projects/memento):
+
+- **[Quick Start](https://hifathom.com/projects/memento/quick-start)** — 5-minute setup guide
+- **[Core Concepts](https://hifathom.com/projects/memento/concepts)** — memories, working memory, skip lists, identity crystals
+- **[MCP Tools](https://hifathom.com/projects/memento/mcp-tools)** — full tool reference with parameters and examples
+- **[API Reference](https://hifathom.com/projects/memento/api)** — REST endpoints, request/response schemas, authentication
+- **[Self-Hosting](docs/self-hosting.md)** — deploy your own instance with Cloudflare Workers + Turso
+
+---
+
+## Development
+
+```bash
+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

package/docs/self-hosting.md

@@ -0,0 +1,86 @@
+# Self-Hosting
+
+The Memento Protocol API runs on Cloudflare Workers with Turso edge databases. The full source is in `saas/`.
+
+For most users, the [hosted service](https://memento-api.myrakrusemark.workers.dev) is the fastest path — free tier, no infrastructure to manage. Self-hosting makes sense if you need data sovereignty or want to modify the API.
+
+## Prerequisites
+
+- [Cloudflare account](https://dash.cloudflare.com/sign-up) (Workers free tier works)
+- [Turso account](https://turso.tech) (free tier: 500 databases, 9GB storage)
+- Node.js 18+
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/): `npm i -g wrangler`
+
+## Setup
+
+### 1. Create the control plane database
+
+```bash
+turso db create memento-control
+turso db tokens create memento-control
+turso db show memento-control --url
+```
+
+Save the URL and token — you'll need them as secrets.
+
+### 2. Create the Vectorize index
+
+```bash
+wrangler vectorize create memento-memories --dimensions=384 --metric=cosine
+```
+
+This powers semantic search. The API degrades gracefully without it (keyword-only recall), but you'll want it.
+
+### 3. Set secrets
+
+```bash
+cd saas
+wrangler secret put MEMENTO_DB_URL    # Turso control plane URL
+wrangler secret put MEMENTO_DB_TOKEN  # Turso control plane token
+wrangler secret put TURSO_API_TOKEN   # Turso Platform API token (for creating workspace DBs)
+wrangler secret put TURSO_ORG         # Your Turso organization slug
+```
+
+The Turso Platform API token is needed because the API auto-creates a separate database per workspace. Get it from [Turso dashboard > Settings > Platform API Tokens](https://turso.tech/app).
+
+### 4. Deploy
+
+```bash
+cd saas
+npm install
+wrangler deploy
+```
+
+Your API is now live at `https://memento-api.<your-subdomain>.workers.dev`.
+
+### 5. Point the MCP server at your instance
+
+In your MCP client config, set the environment variables to your instance:
+
+```json
+{
+  "env": {
+    "MEMENTO_API_KEY": "mp_live_your_key",
+    "MEMENTO_API_URL": "https://memento-api.your-subdomain.workers.dev",
+    "MEMENTO_WORKSPACE": "my-project"
+  }
+}
+```
+
+## What you get
+
+| Feature | Requires |
+|---------|----------|
+| Core memory (store, recall, working memory, skip list) | Workers + Turso |
+| Semantic search (vector embeddings) | + Vectorize + Workers AI |
+| AI consolidation summaries | + Workers AI |
+| Scheduled decay + consolidation | Cron triggers (auto-configured in `wrangler.toml`) |
+
+Workers AI and Vectorize are included in the Cloudflare Workers free tier.
+
+## What's different from hosted
+
+- You manage your own Turso databases and Cloudflare account
+- You handle upgrades by pulling from the repo and redeploying
+- No usage dashboard at hifathom.com (you'd use Cloudflare's dashboard)
+- Signup endpoint creates keys in your control plane database

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "memento-mcp",
+  "version": "0.1.0",
+  "description": "The Memento Protocol — persistent memory for AI agents",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "memento-server": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test test/*.test.js",
+    "test:smoke": "node test-smoke.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "docs/",
+    "LICENSE",
+    "README.md",
+    ".env.example"
+  ],
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai-agent",
+    "persistent",
+    "memento"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.0",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1"
+  }
+}

package/scripts/memento-memory-recall.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Memento SaaS recall — context retrieval from Memento Protocol on every user message.
+# JSON output: systemMessage (user sees count) + additionalContext (model sees details).
+#
+# Calls /v1/context endpoint for memories + skip list matches.
+
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Source credentials from .env (gitignored)
+if [ -f "$SCRIPT_DIR/../.env" ]; then
+    set -a
+    source "$SCRIPT_DIR/../.env"
+    set +a
+fi
+
+MEMENTO_API="${MEMENTO_API_URL:-https://memento-api.myrakrusemark.workers.dev}"
+MEMENTO_KEY="${MEMENTO_API_KEY:?MEMENTO_API_KEY not set — check memento-protocol/.env}"
+MEMENTO_WS="${MEMENTO_WORKSPACE:-fathom}"
+
+INPUT=$(cat)
+USER_MESSAGE=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+
+if [ -z "$USER_MESSAGE" ] || [ ${#USER_MESSAGE} -lt 10 ]; then
+    exit 0
+fi
+
+QUERY="${USER_MESSAGE:0:500}"
+
+# Call Memento SaaS /v1/context
+SAAS_OUTPUT=$(curl -s --max-time 3 \
+    -X POST \
+    -H "Authorization: Bearer $MEMENTO_KEY" \
+    -H "X-Memento-Workspace: $MEMENTO_WS" \
+    -H "Content-Type: application/json" \
+    -d "{\"message\": $(echo "$QUERY" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'), \"include\": [\"memories\", \"skip_list\"]}" \
+    "$MEMENTO_API/v1/context" 2>/dev/null \
+| python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    lines = []
+    count = 0
+
+    # Memory matches
+    memories = data.get('memories', {}).get('matches', [])
+    if memories:
+        for m in memories[:5]:
+            tags = m.get('tags', [])
+            tag_str = f' [{\", \".join(tags)}]' if tags else ''
+            content = m['content'][:120]
+            score = m.get('score', '?')
+            lines.append(f'  {m[\"id\"]} ({m[\"type\"]}, {score}){tag_str} — {content}')
+            count += 1
+
+    # Skip matches (WARNING format)
+    skip_matches = data.get('skip_matches', [])
+    if skip_matches:
+        lines.append('')
+        lines.append('SKIP LIST WARNINGS:')
+        for s in skip_matches:
+            lines.append(f'  ⚠ SKIP: {s[\"item\"]} — {s[\"reason\"]} (expires: {s[\"expires\"]})')
+
+    # Output count and detail as tab-separated on first line, rest follows
+    detail = '\n'.join(lines)
+    print(f'{count}\t{detail}')
+except Exception:
+    print('0\t')
+" 2>/dev/null)
+
+# Parse count and detail
+SAAS_COUNT=$(echo "$SAAS_OUTPUT" | head -1 | cut -f1)
+SAAS_DETAIL=$(echo "$SAAS_OUTPUT" | head -1 | cut -f2-)
+# Append any remaining lines (skip warnings etc.)
+REMAINING=$(echo "$SAAS_OUTPUT" | tail -n +2)
+if [ -n "$REMAINING" ]; then
+    SAAS_DETAIL="$SAAS_DETAIL"$'\n'"$REMAINING"
+fi
+
+if [ -z "$SAAS_COUNT" ] || [ "$SAAS_COUNT" = "0" ]; then
+    exit 0
+fi
+
+DETAIL_TEXT="Memento Recall: ${SAAS_COUNT} memories"
+DETAIL_TEXT="$DETAIL_TEXT"$'\n'"$SAAS_DETAIL"
+DETAIL_TEXT="$DETAIL_TEXT"$'\n'$'\n'"REMINDER: If Memento MCP tools are not loaded, run: ToolSearch query=\"+memento\" max_results=20"
+
+SUMMARY="Memento Recall: ${SAAS_COUNT} memories"
+python3 -c "
+import json, sys
+summary = sys.argv[1]
+detail = sys.argv[2]
+print(json.dumps({
+    'systemMessage': summary,
+    'hookSpecificOutput': {
+        'hookEventName': 'UserPromptSubmit',
+        'additionalContext': detail
+    }
+}))
+" "$SUMMARY" "$DETAIL_TEXT"

package/scripts/memento-precompact-distill.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# PreCompact hook (Memento) — Distill memories from conversation transcript before context compression.
+# Parses JSONL transcript into readable text, then sends it to Memento SaaS /v1/distill endpoint,
+# which extracts key memories, decisions, and observations.
+#
+# Independent of other PreCompact hooks — reads the raw JSONL transcript directly.
+
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INPUT=$(cat)
+
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path' | sed "s|~|$HOME|")
+
+# Only distill if transcript exists and has content
+if [ ! -f "$TRANSCRIPT_PATH" ]; then
+    exit 0
+fi
+
+LINE_COUNT=$(wc -l < "$TRANSCRIPT_PATH")
+if [ "$LINE_COUNT" -lt 2 ]; then
+    exit 0
+fi
+
+# Source credentials from .env (gitignored)
+if [ -f "$SCRIPT_DIR/../.env" ]; then
+    set -a
+    source "$SCRIPT_DIR/../.env"
+    set +a
+fi
+
+MEMENTO_API="${MEMENTO_API_URL:-https://memento-api.myrakrusemark.workers.dev}"
+MEMENTO_KEY="${MEMENTO_API_KEY:?MEMENTO_API_KEY not set — check memento-protocol/.env}"
+MEMENTO_WS="${MEMENTO_WORKSPACE:-fathom}"
+
+# Parse transcript to readable text (use fathom's parser if available, else raw)
+FATHOM_PARSER="/data/Dropbox/Work/fathom/infrastructure/fathom-mcp/scripts/parse-transcript.sh"
+if [ -x "$FATHOM_PARSER" ]; then
+    TRANSCRIPT_TEXT=$("$FATHOM_PARSER" "$TRANSCRIPT_PATH")
+else
+    # Fallback: extract text content directly from JSONL
+    TRANSCRIPT_TEXT=$(jq -r 'select(.type == "user" or .type == "assistant") | .message.content | if type == "string" then . elif type == "array" then [.[] | select(.type == "text") | .text] | join("\n") else empty end' "$TRANSCRIPT_PATH" 2>/dev/null)
+fi
+
+if [ ${#TRANSCRIPT_TEXT} -lt 200 ]; then
+    exit 0  # Too short to distill anything useful
+fi
+
+# Send to Memento SaaS /v1/distill
+RESPONSE=$(curl -s --max-time 30 \
+    -X POST \
+    -H "Authorization: Bearer $MEMENTO_KEY" \
+    -H "X-Memento-Workspace: $MEMENTO_WS" \
+    -H "Content-Type: application/json" \
+    -d "{\"transcript\": $(echo "$TRANSCRIPT_TEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}" \
+    "$MEMENTO_API/v1/distill" 2>/dev/null)
+
+# Report results
+MEMORY_COUNT=$(echo "$RESPONSE" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    print(len(data.get('memories', [])))
+except Exception:
+    print('0')
+" 2>/dev/null)
+
+if [ "$MEMORY_COUNT" -gt 0 ] 2>/dev/null; then
+    python3 -c "
+import json, sys
+msg = sys.argv[1]
+print(json.dumps({'systemMessage': msg}))
+" "Memento Distill: extracted ${MEMORY_COUNT} memories"
+else
+    python3 -c "
+import json, sys
+msg = sys.argv[1]
+print(json.dumps({'systemMessage': msg}))
+" "Memento Distill: no memories extracted"
+fi
+
+exit 0