Delx Memory
Delx Memory is a local-first persistent memory MCP server that provides a shared SQLite store for MCP-capable AI agents, enabling cross-session and cross-tool context continuity. It offers 15 tools for session discovery, reading, full-text search, and controlled mutations.
Session Discovery & Status:
memory_handoff: One-call resume brief with stats and recent keys for quick session restoration.memory_agent_manifest: Machine-readable install/operating instructions for agents (supports Claude, Cursor, Windsurf, Hermes, OpenClaw, Codex configs).memory_connection_status: Check SQLite path readiness and store size without reading values.memory_stats: High-level stats (total keys, DB path, size).memory_capabilities: Inspect server self-description, privacy modes, mutation gating.memory_data_inventory: View memory domains, privacy modes, recommended first calls.
Reading Memory:
memory_get: Exact key lookup; returns value, timestamps, TTL, tags, metadata (null if missing/expired).memory_get_many: Batch retrieve up to 50 keys.memory_list: List keys (no values) with optionalprefix,tag, orsince(delta sync) filters; returns up to 500 results.memory_search: Full-text search across keys, values, and tags using FTS5 with BM25 ranking, word stemming, diacritic folding, and prefix matching (falls back to LIKE scan if FTS5 unavailable).
Writing & Mutations (all require explicit_user_intent: true):
memory_set: Create or update a key-value entry with support for tags, TTL (seconds), and optional metadata; rejects credential-shaped keys/values.memory_set_batch: Upsert up to 50 entries in a single atomic transaction.memory_forget: Delete a single key (idempotent).memory_forget_by_tag: Bulk-delete all entries with a specific tag.memory_export: Dump memory as JSON, JSONL, or Markdown with optionalsince/untiltime windows.
Key Features:
Secret blocking: Automatically refuses to store credential-shaped keys or values (e.g., API keys, tokens).
TTL support: Entries auto-expire (lazy deletion on reads).
Privacy modes: Read tools support
summary(keys/meta only),structured, orrawoutput.Multi-agent namespaces: Isolate keys per agent via
DELX_MEMORY_NAMESPACE.Local storage: All data stored locally at
~/.delx-memory/db.sqlitewith restrictive permissions (0700dir,0600file); no telemetry.
Deployment & Configuration:
Lightweight default
litetransport over stdio to minimize footprint; optional HTTP transport.Environment-configurable DB path, host/port, CORS origin.
Install globally or run via
npx.delx-memory doctorfor health checks (Node version, DB writability, permissions).delx-memory setupto generate client configuration snippets.
delx-memory
Local-first persistent memory MCP server. One shared SQLite store any MCP-speaking agent (Claude Desktop, Cursor, Hermes, OpenClaw, Codex) can read and write — so context survives across sessions AND across tools.
Why
Every chat client has its own ephemeral context. Quit the tab → preferences gone. Switch from Claude Desktop to Cursor → starting from scratch. Pin a side project in Hermes → invisible to the next agent.
delx-memory is a tiny MCP server that exposes a single shared SQLite file as a key/value memory layer. Any client that speaks MCP can read and write the same memory file → real continuity, real cross-tool context.
15 tools — discovery + handoff + batch ops + FTS5 search + mutations gated by intent.
SQLite at
~/.delx-memory/db.sqlite(0700 dir, 0600 file).Secret-blocking: refuses to store credential-shaped keys or values.
TTL support (lazy expiry on read).
Tags + prefix filters + FTS5 full-text search (bm25 ranking, stemming, diacritic folding; LIKE fallback if FTS5 is unavailable).
Mutations require
explicit_user_intent: trueso over-eager agents can't silently rewrite your context.Zero telemetry. Zero phone-home. The file is yours.
Multi-agent namespaces
# Agent A
DELX_MEMORY_NAMESPACE=claude npx -y delx-memory
# Agent B (same machine, isolated keys)
DELX_MEMORY_NAMESPACE=cursor npx -y delx-memoryKeys are stored as namespace::key. Omit the env var for a single global store (default).
Footprint / lightweight mode
Default transport is
lite: tools-only MCP over stdio without loading the MCP SDK (biggest RSS win for always-on agents).Full SDK surface (prompts + resources):
delx-memory --sdkorDELX_MEMORY_TRANSPORT=sdk.Optional HTTP:
delx-memory --http(Express + SDK; still loopback by default).DELX_MEMORY_LEAN=1applies to the SDK path only (skip prompts/resources).doctor --jsonreportsrss_kb. Dominant remaining cost is Node + nativebetter-sqlite3(no embeddings).
Community measurements (custom transport vs SDK) pointed at the SDK tree as the main overhead — see issue #7.
Related MCP server: mcp-memory-rs
Install + run
# Run once (npx will download + boot)
npx -y delx-memory doctor
# Or install globally
npm install -g delx-memory
delx-memory doctorThe doctor command checks Node version, DB writability, and file permissions, then prints next steps.
HTTP (v2 stateless)
Default is stdio. Optional Streamable HTTP — no session id, JSON responses, loopback only:
npx -y delx-memory --http
# GET http://127.0.0.1:3030/health
# POST http://127.0.0.1:3030/mcp (sessionless)Env: DELX_MEMORY_HOST, DELX_MEMORY_PORT, DELX_MEMORY_TRANSPORT=http.
Wire it into your MCP client
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"delx-memory": {
"command": "npx",
"args": ["-y", "delx-memory"]
}
}
}Then restart Claude Desktop. See examples/claude-desktop.json.
Cursor
Add to ~/.cursor/mcp.json. See examples/cursor.json.
Hermes
See examples/hermes.md.
OpenClaw
See examples/openclaw.md.
Codex CLI
See examples/codex.toml.
What makes it different (honest)
delx-memory | Typical cloud memory | Graph memory MCP | |
Data leaves your machine | No | Yes | Usually no |
Multi-client same store | Yes (one SQLite) | Account-bound | Process-local |
Agent mutation safety |
| Varies | Rare |
Secret storage | Hard-refused | Often allowed | Often allowed |
Default RSS path | Lite (no MCP SDK) | N/A | Full stack |
Multi-agent isolation |
| Tenants | Manual |
Search | FTS5 bm25 | Embeddings (cost/leak) | Graph walk |
Not a vector DB. Not a second brain SaaS. Local continuity for agents that already have a model.
Tools (15)
Session start
Tool | Purpose |
| One-call resume brief: stats + recent keys (optional values). Prefer this at session start. |
| Machine install/ops contract for agents. |
| Readiness + store size. |
| Self-description for agents. |
Reads
Tool | Purpose |
| Keys only; filters: |
| Exact key or batch (max 50). |
| FTS5 bm25 (+ LIKE fallback). See search quickstart. |
Mutations (require explicit_user_intent: true)
Tool | Purpose |
| Upsert one key or up to 50 in one transaction. |
| Delete one key or by tag. |
| Dump JSON / JSONL / Markdown. |
Every mutation refuses to run unless the caller passes explicit_user_intent: true. The intent: an agent that decides on its own to update memory must show its work. The user can see the flag in the tool call and reject it if they didn't ask.
Privacy contract (read this)
delx-memory is NOT a secrets manager. Use macOS Keychain / gnome-keyring / Windows Credential Manager for those.
What we refuse to store:
Keys matching:
oauth,token,secret,password,cookie,refresh,api_key,api-key,apikey,bearer,credential,session_id(case-insensitive).Values matching credential shapes:
JWT tokens (
eyJ…)Bearer <token>headersStripe
sk_live_…/sk_test_…Slack
xoxb-…/xoxp-…/ etc.GitHub
github_pat_…/ghp_…/gho_…/ghs_…/ghr_…OpenAI / Anthropic
sk-…(with realistic length)AWS access keys
AKIA…Authorization: <scheme> <token>strings
Nested objects are walked recursively — a nested field named
refresh_token(even with an empty value) is rejected.
What stays local:
The DB file lives at
~/.delx-memory/db.sqlite.Directory is created with mode
0700; file with mode0600. (Best effort on Windows / WSL / non-POSIX filesystems.)Nothing is uploaded. No telemetry. No phone-home.
What we do NOT promise:
Other users of the same machine (root, your
sudo-using housemate) can read the file. Use full-disk encryption (FileVault, BitLocker, LUKS) if that matters.TTL is best-effort. Expired rows are deleted lazily on next read; SQLite doesn't
VACUUMautomatically, so freed pages may sit on disk. For sensitive ephemera, treat the DB file like any other unencrypted dotfile.No durability promise. Back up
~/.delx-memory/db.sqlitelike any other dotfile if you care about losing it.
Example session
agent> memory_stats({})
→ { total_keys: 0, db_path: "/Users/me/.delx-memory/db.sqlite", … }
user> Remember that I prefer concise responses in pt-BR.
agent> memory_set({
key: "user_preferences",
value: { language: "pt-BR", verbosity: "concise" },
tags: ["profile", "preferences"],
explicit_user_intent: true
})
→ { action: "created", key: "user_preferences", … }
# … new chat, possibly different tool …
agent> memory_list({ tag: "preferences" })
→ [{ key: "user_preferences", updated_at: … }]
agent> memory_get({ key: "user_preferences" })
→ { found: true, value: { language: "pt-BR", verbosity: "concise" } }Storage layout
Default path |
|
Override |
|
Directory mode |
|
File mode |
|
Schema |
|
Indexes | partial index on |
Per-value cap | 64 KB (JSON-serialized) |
Per-key cap | 512 chars |
CLI
delx-memory Start MCP stdio server
delx-memory --http Start local HTTP MCP server (127.0.0.1:3030)
delx-memory setup Print MCP client config snippets
delx-memory setup --json Print as JSON
delx-memory doctor Health check + next steps
delx-memory doctor --json Health check as JSON
delx-memory version Print versionEnvironment
Var | Default | Purpose |
|
| DB file location |
|
|
|
|
| HTTP host |
|
| HTTP port |
|
| CORS origin |
Development
git clone https://github.com/davidmosiah/delx-memory
cd delx-memory
npm install
npm test # typecheck + build + smoke + secret-detector + ttl + tag-delete + metadataSee AGENTS.md for repo conventions, SECURITY.md for the security model and reporting policy, and CONTRIBUTING.md for PR rules.
License
MIT © 2026 David Batista. Code of Conduct.
Skill or MCP
Same package, two doors. MCP registers tools on stdio/HTTP. The skill can drive the same tools through the CLI when the client has no MCP:
npx -y delx-memory call memory_connection_status --json '{}'Copy skill/SKILL.md into your agent skills dir.
Available Tools
15 toolsmemory_agent_manifestARead-onlyIdempotent
Machine-readable install and operating instructions for AI agents. Call first when onboarding. Supports privacy_mode documentation for read tools.
Inputs: client (required).
memory_capabilitiesBRead-onlyIdempotent
Self-description of this MCP including privacy modes and mutation gating.
Inputs: privacy_mode.
memory_connection_statusARead-onlyIdempotent
Local SQLite path readiness and size without reading entry values. Safe first call every session.
Inputs: privacy_mode.
memory_data_inventoryARead-onlyIdempotent
Static inventory of memory domains, privacy modes and recommended first calls. No live value reads.
Inputs: privacy_mode.
memory_exportARead-onlyIdempotent
Dump the memory store as JSON, JSONL, or Markdown. Optional since/until window on updated_at. Use for backup/inspection. Requires explicit_user_intent: true.
Inputs: format (required), explicit_user_intent (required), since, until.
memory_forgetADestructiveIdempotent
Delete a single key from memory. Idempotent: returns existed=false if the key was not present. Requires explicit_user_intent: true.
Inputs: key (required), explicit_user_intent (required).
memory_forget_by_tagADestructiveIdempotent
Delete every entry carrying the given tag. Returns deleted_count. Requires explicit_user_intent: true.
Inputs: tag (required), explicit_user_intent (required).
memory_getARead-onlyIdempotent
Exact key lookup. Returns the stored value plus timestamps, ttl, tags, metadata. Returns null if missing or expired. Optional privacy_mode=summary omits full values.
Inputs: key (required), privacy_mode.
memory_get_manyARead-onlyIdempotent
Batch exact-key lookup (max 50). Missing keys omitted. Respects DELX_MEMORY_NAMESPACE.
Inputs: keys (required), privacy_mode.
memory_handoffARead-onlyIdempotent
Returns store stats + the most recently updated keys (optional values). Designed for session start: one call instead of stats+list+get fan-out. Namespace-aware.
Inputs: limit (required), include_values (required).
memory_listARead-onlyIdempotent
List keys with optional prefix, tag, or since (updated_at) filter. Returns keys + timestamps + tags only — call memory_get for values. Scoped by DELX_MEMORY_NAMESPACE when set.
Inputs: limit (required), tag, since, prefix, +1 more.
memory_searchARead-onlyIdempotent
Full-text search across keys, values AND tags. Uses an FTS5 index with bm25 relevance ranking (key-weighted), word-stemming, diacritic folding and prefix matching — so multi-word, partial and accent-insensitive queries all hit, ranked by relevance. Falls back to a LIKE substring scan if the SQLite build lacks FTS5. Returns top N matches with a snippet. Case-insensitive. privacy_mode=summary omits snippets.
Inputs: limit (required), query (required), privacy_mode.
memory_setAIdempotent
Create or update a key in memory. Rejects credential-shaped keys or values. Requires explicit_user_intent: true. Returns whether the row was created or updated.
Inputs: key (required), value (required), explicit_user_intent (required), tags, +2 more.
memory_set_batchAIdempotent
Upsert up to 50 entries in one SQLite transaction. One explicit_user_intent covers the batch. Rejects secret-shaped keys/values. Namespace-aware.
Inputs: entries (required), explicit_user_intent (required).
memory_statsARead-onlyIdempotent
High-level stats about the local memory store. Safe to call first on every session to gauge whether the store is empty, small, or large.
Inputs: privacy_mode.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Core data operations are distinct, but the six introspection/status tools (agent_manifest, connection_status, data_inventory, capabilities, stats, handoff) overlap in purpose—several report store size or describe privacy modes, and handoff explicitly subsumes stats+list+get. Detailed descriptions mitigate confusion but don't fully eliminate it.
All tools share a consistent memory_ snake_case prefix, but the set mixes noun-style names (memory_stats, memory_handoff, memory_capabilities) with verb-style names (memory_get, memory_set, memory_forget). The prefix keeps it readable, but there is no consistent verb_noun pattern.
15 tools is within the acceptable range for a memory server, and batch/search/export variants earn their place. It feels slightly heavy because several status/introspection tools could be consolidated (e.g., stats vs connection_status vs handoff).
Full lifecycle coverage is present: set/upsert, single and batch get, list/search, forget/forget_by_tag, export, and session-start handoff. Batch operations, namespace awareness, and privacy modes round out the surface with no obvious dead ends.
Maintenance
Related MCP Connectors
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Governed personal world model and memory for your AI agent. Pair once, connect over MCP.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA local-first MCP memory server providing persistent, searchable memory for AI agents, powered by SQLite.1Functional Source , Version 1.1, ALv2 Future
- AlicenseNot gradedqualityBmaintenanceLocal-first MCP memory server providing persistent, versioned, queryable memory for AI agents using JSON categories and SQLite FTS5, with optional fleet sync.2Apache 2.0
- AlicenseCqualityBmaintenanceLocal-first, governable long-term memory for AI agents. Provides SQLite-backed storage, cross-session recall, and traceable memory corrections through a standard MCP interface.401MIT
- AlicenseNot gradedqualityBmaintenanceEnables concurrent MCP clients to share a persistent SQLite-backed key-value memory store with semantic search, write attribution, and audit history.MIT