Setup Guide

1. MCP Client Setup

Add the Lodis MCP server to your client’s config file. Same JSON for every client — just change the file path.

{
  "mcpServers": {
    "lodis": {
      "command": "npx",
      "args": ["-y", "lodis"]
    }
  }
}

2. System Prompt Configuration

Tell your AI to use Lodis by default. Add this snippet to your system prompt or instructions file:

Use Lodis MCP tools for all persistent memory. At the start of
conversations, call memory_search with relevant terms to retrieve
context. When the user states a preference, corrects an assumption,
shares personal context, or provides information useful across future
conversations, save it with memory_write.

Where to put it

## Memory — CRITICAL OVERRIDE

**DO NOT use the built-in file-based auto-memory system.** Never create,
read, or write to `MEMORY.md` or any files in the
`~/.claude/projects/.../memory/` directory. That system is fully
replaced by Lodis.

**USE Lodis MCP tools for ALL persistent memory.** Lodis is the
single source of truth.

### At conversation start
- Call `memory_search` with terms relevant to the user's request to
  retrieve prior context

### When to write
- `memory_write` — user states a preference, corrects an assumption,
  shares personal context, or says anything useful for future conversations
- `memory_confirm` — user validates a recalled fact
- `memory_correct` — user corrects a stored memory
- `memory_flag_mistake` — a memory turns out to be wrong

### When to search
- `memory_search` — before answering questions where prior context
  would help
- `memory_context` — token-budget-aware retrieval for building responses
- `memory_briefing` — entity summaries (people, projects, etc.)

### Rules
- Never duplicate memories to both Lodis and the built-in file system
- Treat Lodis memories as the persistent record — they survive across
  all MCP-connected tools (Claude Code, Cursor, Windsurf, Claude Desktop)
- When the user says "remember this," save immediately via `memory_write`

3. First Run — Seeding Your Memory

Once Lodis is connected, tell your AI assistant:

Your assistant will call memory_onboard and:

1. 1
   Scan your connected tools (calendar, email, GitHub) to extract people, projects, and context
2. 2
   Interview you with targeted questions based on what it found
3. 3
   Seed 30-50 memories with entity types and connections

Importing existing memories

If you already have memories in other tools, your AI can import them:

Review your memories at localhost:3838. Confirm what’s right, correct what’s wrong.

4. Cloud Setup

Cloud mode syncs your memories across devices via Turso. All data encrypted at rest with AES-256-GCM.

1. 1Sign up

   Create an account at app.lodis.ai

2. 2Create an API token

   Go to Settings → API Tokens → Generate Token. Copy it — you’ll need it for MCP client config.

3. 3Configure your MCP client

   Use the HTTP transport with your API token:

   {
     "mcpServers": {
       "lodis": {
         "type": "streamable-http",
         "url": "https://app.lodis.ai/api/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_TOKEN"
         }
       }
     }
   }

   Copy

Already running locally? Use memory_migrate to move your existing memories to cloud.

5. Local HTTP Mode

Want to connect remote clients to a self-hosted Lodis instance? Run the HTTP server with Bearer token authentication:

lodis --serve

1. 1Create an API token

   Open the dashboard at localhost:3838 → Settings → API Tokens → Generate Token.

2. 2Configure your remote client

   {
     "mcpServers": {
       "lodis": {
         "type": "streamable-http",
         "url": "http://localhost:3939/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_TOKEN"
         }
       }
     }
   }

   Copy

This gives you the same remote access as cloud mode, but running entirely on your own machine.