@mementoagi/proxy

Local stdio-to-HTTP bridge for Memento Cloud. Connects your IDE's AI to persistent memory.

Quick Start

# Install globally (optional)
npm install -g @mementoagi/proxy

# Authenticate
memento-login

# Or run directly via npx
npx @mementoagi/proxy

IDE Setup

Cursor

Add to .cursor/mcp.json (project) or global MCP settings:

{
  "mcpServers": {
    "memento-cloud": {
      "command": "/bin/zsh",
      "args": ["-lc", "npx -y @mementoagi/proxy"],
      "env": {
        "MEMENTO_API_KEY": "mk_your_key_here",
        "MEMENTO_SERVER_URL": "https://api.mementoagi.com"
      }
    }
  }
}

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["-y", "@mementoagi/proxy"]
    }
  }
}

Other MCP-compatible IDEs

Same pattern — set the command to npx -y @mementoagi/proxy.

Authentication

Option 1: Login command (recommended)

memento-login

Prompts for email/password, stores your API key in ~/.memento/credentials. The proxy reads from there automatically.

Option 2: Environment variable

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["-y", "@mementoagi/proxy"],
      "env": {
        "MEMENTO_API_KEY": "mk_your_key_here"
      }
    }
  }
}

Option 3: Self-hosted server

Point the proxy at your own Memento server:

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["-y", "@mementoagi/proxy"],
      "env": {
        "MEMENTO_API_KEY": "mk_your_key_here",
        "MEMENTO_SERVER_URL": "https://memento.your-company.internal"
      }
    }
  }
}

Advanced: Local Org Data

For organizations that require data to stay on-device (security policies, compliance, etc.), the proxy can store org-scoped data locally while routing everything else to the cloud.

org:ironclad/* → local filesystem
core/*, personal/*, system/* → Memento Cloud

Setup

Add MEMENTO_LOCAL_ORGS to your MCP config. Format: slug:/absolute/path (comma-separated for multiple orgs).

{
  "mcpServers": {
    "memento-cloud": {
      "command": "/bin/zsh",
      "args": ["-lc", "npx -y @mementoagi/proxy"],
      "env": {
        "MEMENTO_API_KEY": "mk_your_key_here",
        "MEMENTO_SERVER_URL": "https://api.mementoagi.com",
        "MEMENTO_LOCAL_ORGS": "ironclad:/Users/me/memento-orgs/ironclad"
      }
    }
  }
}

When MEMENTO_LOCAL_ORGS is set, any file operation (read-file, write-file, list-files, delete-file, str-replace, rename-file) whose path starts with org:<slug>/ is handled directly on the local filesystem. The LLM and the MCP tools work identically — the routing is transparent.

Multiple local orgs

"MEMENTO_LOCAL_ORGS": "ironclad:/Users/me/orgs/ironclad,acme:/Users/me/orgs/acme"

When to use this

Most users don't need local org routing. Use it when:

• Company security policy prohibits storing work data on external cloud services
• Regulatory requirements mandate on-device data residency
• You want to keep org knowledge in a local git repo

If none of these apply, the default cloud setup handles everything including org data.

How It Works

The proxy is a stdio-to-HTTP bridge with optional local routing:

IDE ←→ stdin/stdout ←→ proxy ─┬─→ HTTP ─→ Memento Cloud (core, personal, system)
                               └─→ local fs (org data, when MEMENTO_LOCAL_ORGS is set)

1. IDE spawns the proxy as a child process
2. IDE sends JSON-RPC messages over stdin
3. Proxy inspects the request path:
   • If it matches a local org → handles the file operation directly on disk
   • Otherwise → forwards to the server via HTTP POST with your API key
4. Proxy writes the response to stdout
5. IDE receives the response

The proxy has zero dependencies, handles network errors gracefully, and exits cleanly when the IDE closes the connection.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MEMENTO_API_KEY | (from ~/.memento/credentials) | Your Memento API key | | MEMENTO_SERVER_URL | http://localhost:3000 | Server URL | | MEMENTO_LOCAL_ORGS | (none) | Comma-separated slug:/path mappings for local org storage |

Error Handling

| Scenario | Behavior | |----------|----------| | No API key | Returns JSON-RPC error with signup link | | Invalid API key (401) | Returns error with key management link | | Rate limited (429) | Returns error asking to wait | | Server error (5xx) | Returns error noting temporary unavailability | | Network unreachable | Returns error noting memory features are paused |

In all error cases, the IDE continues working normally — memory features are paused, not broken.

License

MIT