Skip to main content
Glama

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.

npm version GitHub Release npm downloads status: beta license: MIT node: >=20 Verified Release Index

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: true so 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-memory

Keys 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 --sdk or DELX_MEMORY_TRANSPORT=sdk.

  • Optional HTTP: delx-memory --http (Express + SDK; still loopback by default).

  • DELX_MEMORY_LEAN=1 applies to the SDK path only (skip prompts/resources).

  • doctor --json reports rss_kb. Dominant remaining cost is Node + native better-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 doctor

The 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

explicit_user_intent

Varies

Rare

Secret storage

Hard-refused

Often allowed

Often allowed

Default RSS path

Lite (no MCP SDK)

N/A

Full stack

Multi-agent isolation

DELX_MEMORY_NAMESPACE

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

memory_handoff

One-call resume brief: stats + recent keys (optional values). Prefer this at session start.

memory_agent_manifest

Machine install/ops contract for agents.

memory_connection_status / memory_stats

Readiness + store size.

memory_capabilities / memory_data_inventory

Self-description for agents.

Reads

Tool

Purpose

memory_list

Keys only; filters: prefix, tag, since (delta sync).

memory_get / memory_get_many

Exact key or batch (max 50).

memory_search

FTS5 bm25 (+ LIKE fallback). See search quickstart.

Mutations (require explicit_user_intent: true)

Tool

Purpose

memory_set / memory_set_batch

Upsert one key or up to 50 in one transaction.

memory_forget / memory_forget_by_tag

Delete one key or by tag.

memory_export

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> headers

    • Stripe 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 mode 0600. (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 VACUUM automatically, 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.sqlite like 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

~/.delx-memory/db.sqlite

Override

DELX_MEMORY_PATH env var

Directory mode

0700

File mode

0600

Schema

memory(key PRIMARY KEY, value, created_at, updated_at, ttl_expires_at, tags, metadata)

Indexes

partial index on ttl_expires_at, plus tags, updated_at

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 version

Environment

Var

Default

Purpose

DELX_MEMORY_PATH

~/.delx-memory/db.sqlite

DB file location

DELX_MEMORY_TRANSPORT

stdio

stdio or http

DELX_MEMORY_HOST

127.0.0.1

HTTP host

DELX_MEMORY_PORT

3030

HTTP port

DELX_MEMORY_ALLOWED_ORIGIN

http://HOST: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 + metadata

See 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 tools
memory_agent_manifestA
Read-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_capabilitiesB
Read-onlyIdempotent

Self-description of this MCP including privacy modes and mutation gating.

Inputs: privacy_mode.

memory_connection_statusA
Read-onlyIdempotent

Local SQLite path readiness and size without reading entry values. Safe first call every session.

Inputs: privacy_mode.

memory_data_inventoryA
Read-onlyIdempotent

Static inventory of memory domains, privacy modes and recommended first calls. No live value reads.

Inputs: privacy_mode.

memory_exportA
Read-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_forgetA
DestructiveIdempotent

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_tagA
DestructiveIdempotent

Delete every entry carrying the given tag. Returns deleted_count. Requires explicit_user_intent: true.

Inputs: tag (required), explicit_user_intent (required).

memory_getA
Read-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_manyA
Read-onlyIdempotent

Batch exact-key lookup (max 50). Missing keys omitted. Respects DELX_MEMORY_NAMESPACE.

Inputs: keys (required), privacy_mode.

memory_handoffA
Read-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_listA
Read-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_setA
Idempotent

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_batchA
Idempotent

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_statsA
Read-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

    A3.8/5.0

    Scored across 15 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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).

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A local-first MCP memory server providing persistent, searchable memory for AI agents, powered by SQLite.
      1
      Functional Source , Version 1.1, ALv2 Future
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-first MCP memory server providing persistent, versioned, queryable memory for AI agents using JSON categories and SQLite FTS5, with optional fleet sync.
      2
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Local-first, governable long-term memory for AI agents. Provides SQLite-backed storage, cross-session recall, and traceable memory corrections through a standard MCP interface.
      40
      1
      MIT