Limitless

Limitless

A portable, self-hosted memory layer for AI tools — store context, memories, and handoffs once and access them from Claude, ChatGPT, or any MCP-compatible client.

For more information, visit limitless-ai.dev.

How it works

Limitless runs as a Cloudflare Worker with D1 (SQLite) for structured storage and Vectorize for semantic search. You authenticate with Google OAuth, then store entries that any connected AI client can retrieve via MCP. Each user's data is encrypted at rest with a per-user AES-GCM key derived from your SERVER_ENCRYPTION_SECRET.

Cloudflare Workers uses an isolated, per-request execution model — each invocation spins up a fresh context with no persistent memory. Plaintext is never accumulated between requests. Combined with AES-GCM encryption at rest, the hosting provider cannot read stored payloads. See how Workers works.

For a visual overview, see the architecture diagram.

---

Prerequisites

• Cloudflare account (free tier works for personal use)
• Node.js + npm
• Wrangler CLI: npm install -g wrangler
• Google Cloud project with OAuth 2.0 credentials
• Authorized redirect URI: https://<your-worker>.workers.dev/callback

---

Deploy your own instance

1. Clone and install

git clone https://github.com/JDS300/limitless-mcp
cd limitless-mcp
npm install

2. Create Cloudflare resources

npx wrangler login
npx wrangler d1 create limitless-db
npx wrangler vectorize create limitless-index --dimensions=768 --metric=cosine
npx wrangler vectorize create-metadata-index limitless-index --propertyName user_id --type string
npx wrangler vectorize create-metadata-index limitless-index --propertyName type --type string
npx wrangler vectorize create-metadata-index limitless-index --propertyName status --type string

3. Update wrangler.toml

After running wrangler d1 create, copy the database_id from the output and update it in wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "limitless-db"
database_id = "<paste your database_id here>"

Also create a KV namespace and update the id:

npx wrangler kv namespace create OAUTH_KV

[[kv_namespaces]]
binding = "OAUTH_KV"
id = "<paste your kv namespace id here>"

4. Google OAuth setup

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Create an OAuth 2.0 Client ID (Web application)
3. Add https://<your-worker>.workers.dev/callback as an authorized redirect URI
4. Copy the Client ID and Client Secret — you'll use them in the next step

5. Set secrets

npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler secret put SERVER_ENCRYPTION_SECRET

| Secret | Purpose | |--------|---------| | GOOGLE_CLIENT_ID | Google OAuth app client ID | | GOOGLE_CLIENT_SECRET | Google OAuth app client secret | | COOKIE_ENCRYPTION_KEY | Encrypts OAuth session cookies — generate with openssl rand -base64 32 | | SERVER_ENCRYPTION_SECRET | Per-user AES-GCM key derivation — generate with openssl rand -base64 32 (must differ from COOKIE_ENCRYPTION_KEY) |

6. Run the database migrations

npx wrangler d1 execute limitless-db --remote --file=migrations/0001_initial.sql
npx wrangler d1 execute limitless-db --remote --file=migrations/0002_v2_schema.sql
npx wrangler d1 execute limitless-db --remote --file=migrations/0003_v3_schema.sql

7. Deploy

npm run deploy

Your worker will be live at https://limitless-mcp.<your-subdomain>.workers.dev.

---

Connecting MCP clients

Limitless supports two integration paths:

• MCP clients (Claude Desktop, Claude Code, any MCP-native tool): plug-and-play via the MCP config below.
• Non-MCP tools (ChatGPT, Gemini, any web UI): use the system prompt / custom instructions snippet. This is a fully supported path.

Claude / Claude Code

Add to your claude_desktop_config.json (or Claude Code settings):

{
  "mcpServers": {
    "limitless": {
      "url": "https://limitless-mcp.<your-subdomain>.workers.dev/mcp"
    }
  }
}

Add to your system prompt or project instructions:

Call bootstrap_session with the appropriate namespace before any task.
Use limitless-mcp for all context — do not assert facts without searching.
Cross-namespace writes go through handoffs, never direct mutations.
If a Limitless entry conflicts with native memory, prefer the source
with the newer timestamp and surface the discrepancy.

ChatGPT

Add to your custom instructions:

I use a personal memory tool called Limitless at https://limitless-mcp.<your-subdomain>.workers.dev.
At the start of each session, retrieve my context (identity, active projects, handoffs) and search
for relevant information before answering. Confirmed entries are facts; hedge unconfirmed ones.

---

MCP Tools

| Tool | Description | |------|-------------| | bootstrap_session | Load session context — identity, rules, active projects, handoffs, recent decisions. Call at session start with your namespace. | | store_entry | Save an entry (identity, rules, catalog, framework, decision, project, handoff, resource, or memory). Optionally create relationships in the same call. | | search_memory | Semantic search across stored entries. Filter by domain type and namespace. | | explore_context | Walk the relationship graph from any entry to find all connected context. | | add_relationship | Create a typed, temporal relationship between two entries. | | expire_relationship | Mark a relationship as no longer current (historical queries still find it). | | get_handoffs | Retrieve all pending handoff items. | | archive_handoff | Mark a handoff as completed. | | get_pinned_context | Retrieve pinned entries (deprecated — use bootstrap_session). | | get_resource | Look up a resource entry by name or tag. | | update_entry | Update entry fields including content, tags, namespace, pinned, confirmed_at, and supersedes. | | delete_entry | Permanently remove an entry and its relationships. |

---

Entry domains

Entries are organized into 9 domain types. Each domain serves a specific role in the knowledge architecture.

| Domain | Purpose | Typically pinned? | |--------|---------|-------------------| | identity | Who you are — name, role, org, style preferences, banned language | Always | | rules | Behavioral directives — guardrails, consistency checks, pushback rules | Always | | catalog | Service offerings with pricing, descriptions, inclusions | No — searched on demand | | framework | Methodologies, models, repeatable approaches | No — searched on demand | | decision | Decisions with date, rationale, and optional supersedes link | Recent/important only | | project | Project status, goals, client, phase, key deliverables | Active projects | | handoff | Cross-session tasks and follow-ups | needs_action items at bootstrap | | resource | Templates, prompts, URIs, reusable artifacts | No — deterministic lookup | | memory | Catch-all for anything that doesn't fit the above | Varies |

All entries belong to a namespace (work, personal, or shared). shared entries appear in every namespace. Pin entries with pinned: true to include them in bootstrap_session results.

Decision chains

Decision entries support a supersedes field — a reference to the ID of the decision being overridden. This creates an explicit audit chain and prevents relitigating past decisions.

Staleness and confirmed_at

Set confirmed_at (unix ms) when you've verified an entry is current. System prompts should instruct the AI to flag entries older than 12–18 months and ask the user to re-confirm.

Relationship graph

Entries can be connected by typed, directional, temporal relationships.

| Relationship | Meaning | Example | |-------------|---------|---------| | uses_framework | Work product uses a methodology | Proposal → Three Patterns | | priced_from | Pricing sourced from catalog | SOW → AI Workshop $5,000 | | decided_by | Shaped by a decision | Project scope → Decision | | supersedes | Newer decision replaces older | Decision B → Decision A | | delivered_to | Work product for a project | Proposal → Client XYZ | | related_to | General association | Any → Any |

Relationships have temporal validity — valid_from and valid_to timestamps. When a fact changes, the old relationship expires and a new one is created. Use explore_context to walk the graph from any entry.

Bootstrap protocol

Call bootstrap_session(namespace) at the start of every session. It returns:

1. Identity — who you are, style preferences
2. Rules — behavioral directives and guardrails
3. Active projects — pinned project summaries
4. Pending handoffs — unactioned cross-session tasks
5. Recent decisions — last 30 days, pinned or high-importance

Total: ~800-1500 tokens. Everything else is retrieved on demand via search_memory or explore_context.

Namespace isolation

• Writes: namespace is required. Cross-namespace writes create a handoff in the target namespace.
• Reads: default to session namespace + shared. Cross-namespace reads require explicit cross_namespace parameter and are read-only (no trace left in target namespace).

---

Admin interface

Visit /admin on your deployed Worker to browse and manage entries without going through an AI. Authenticate with your Google account. You can filter by namespace, type, and pinned status, assign namespaces to existing entries, pin/unpin, and delete.

The admin UI uses a REST API (GET/PATCH/DELETE /api/entries) authenticated via a short-lived HMAC session token issued at /admin/callback.

The admin UI supports filtering by all 9 domain types and namespace, viewing relationships for any entry, and bulk selection with bulk delete for post-import cleanup.

OAuth providers

Limitless is built on Cloudflare's OAuth provider library, which supports Google, GitHub, Microsoft, LinkedIn, and others. The encryption key scheme ({provider}:{user_id}) is designed so adding a new provider requires no key rotation for existing users. Currently only Google is wired up; adding a second provider is a small auth-handler change.

Conflict resolution

When a Limitless entry and an AI's native memory disagree:

1. AI finds a Limitless entry on the current topic
2. AI checks native memory for anything related
3. If conflict → both versions surfaced with timestamps, user picks
4. User confirms → call update_entry with tags: "confirmed" on the correct entry
5. Future sessions: confirmed Limitless entries are trusted without asking

---

Import and migration

Limitless supports importing from existing knowledge stores:

• AI Vault (structured): Import from CLAUDE.md / CONTEXT.md / SERVICE_CATALOG.md pattern. Content maps directly to domain types.
• Obsidian / organic vault: AI reads, classifies, and proposes domain mappings for user review.
• Cross-AI memory: Export from ChatGPT, Gemini, or other AI services. Prompt-driven, maps to Limitless domains.

Use POST /api/entries/bulk for batch import. Import prompts are stored as resource entries in Limitless for retrieval.

---

License

MIT