🤖 MCP Overview

One hosted Model Context Protocol server exposes memory as tools for Claude Code, Claude Desktop, and any MCP-capable agent. It lives in memory-backend (repo composable-memory-api) at POST /mcp — Streamable HTTP, stateless, no sessions. There is no @lighthouse-ai/* MCP package to install.

• Hosted HTTP server - memory-backend at POST /mcp. Per-user engines (batched or memwal, picked server-side by MEMORY_ENGINE), Dynamo-backed batched index, Clerk JWT or dev token, BYOK key vault (see BYOK Keys tutorial).
• Tool list adapts to the engine - both engines share the common tools; batched adds flush + rebuild; memwal adds analyze/verify/restore/repin/blob-ids. When the user has no Lighthouse key yet, the server exposes only the three key tools so the agent can self-onboard.

MEMORY_ENGINE accepts batched or memwal (unknown values error out). Batched reuses MEMORY_* / S3_* / LIGHTHOUSE_API_KEY; memwal uses MEMWAL_* (+ optional LIGHTHOUSE_API_KEY for pinning).

Connect clients (HTTP)

Point the client at POST memory-api.lighthouse.storage/mcp with Authorization: Bearer <token> — a Clerk session JWT, or MCP_BEARER_TOKEN in dev.

curl -X POST http://localhost:4000/mcp \
  -H "authorization: Bearer $JWT" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory_remember","arguments":{"content":"Prefers TS strict mode","tags":["preference"]}}}'

The dashboard's mcpTool() (composable-memory-dashboard/src/api.ts) does the same and parses the SSE envelope (event: message + data: {...}) or plain JSON:

import { mcpTool } from './api' // composable-memory-dashboard/src/api.ts

await mcpTool(apiUrl, jwt, 'memory_remember', { content: 'Prefers TS strict mode', tags: ['preference'] })
await mcpTool(apiUrl, jwt, 'memory_recall', { query: 'coding preferences', limit: 5 })
await mcpTool(apiUrl, jwt, 'memory_flush', {})

Available tools are the common + batched or memwal sets, plus the three key tools when no BYOK key exists.

Method	Path	Auth	Notes
POST	/mcp	Bearer (dev token or Clerk JWT)	Streamable HTTP; per-user engine; key-only memory_api_key_* mode when no BYOK key
GET	/mcp	-	405 Use POST /mcp for MCP
DELETE	/mcp	-	{ ok: true, stateless: true } (no sessions)
GET	/.well-known/oauth-protected-resource	No	{ resource, authorization_servers, scopes_supported, bearer_methods_supported } for ChatGPT/Claude discovery
GET	/	No	{ ok, service: 'memory-sdk', mcpPath, auth, vault }

Rotate the JWT when it expires (dashboard getToken({ template: 'mcp-long' }) refresh). Request bodies are capped at 4 MB; CORS allows authorization, content-type, accept, mcp-session-id, last-event-id.

{
  "mcpServers": {
    "memory-sdk-hosted": {
      "type": "http",
      "url": "https://memory-api.lighthouse.storage/mcp",
      "headers": { "Authorization": "Bearer <CLERK_JWT>" }
    }
  }
}

Tool map

	Tool	Reference
Both	memory_remember, memory_recall, memory_list, memory_get, memory_forget, memory_status, memory_snapshot_index, memory_restore_local (batched) / memory_rebuild_local (memwal)	Common Tools
Batched only	memory_flush, memory_rebuild_index	Batched Tools
Memwal only	memory_analyze, memory_verify, memory_restore_index, memory_repin_pending, memory_blob_ids	Memwal Tools
Key-only mode (no Lighthouse key yet)	memory_api_key_save, memory_api_key_status, memory_api_key_delete	BYOK Keys tutorial

forget() tells the truth per backend: batched on local-fs/S3 hard-deletes (blob removed once unreferenced); on Lighthouse it stops renewal. Memwal removes the local copy and unpins - the relayer has no delete API, so the encrypted blob lapses on its own and may still surface in recall as indexed: false.

What it looks like in practice

You: remember that our staging environment is at staging.acme.dev and redeploys on every merge to develop

Agent: (calls memory_remember) Saved.

• days later, new session -

You: where do I check the latest staging build?

Agent: (calls memory_recall) Your staging environment is at staging.acme.dev - it redeploys on every merge to develop.

tip

Batched buffers writes: encourage durable habits in your agent's system prompt, e.g. "Before ending a session, call memory_flush if any memories are pending." Memwal needs no flush - every write is already on the network.

Key-only mode + vault

When no BYOK key exists, POST /mcp still serves three tools so the agent can self-onboard:

Tool	Purpose
memory_api_key_save ({ lighthouseKey })	Store the lh_... key. Only last4 is ever returned. NOTE: the key passes through chat history - prefer the dashboard field on shared machines.
memory_api_key_status	{ saved, last4, updatedAt } - last4: 'server' means the shared env fallback is active.
memory_api_key_delete	Delete the saved key; future uploads fall back or fail.

The same operations exist as REST: PUT /v1/keys, GET /v1/keys/status, DELETE /v1/keys.