{
  "markdown": "# delx-memory\n\n> 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.\n\n[![npm version](https://img.shields.io/npm/v/delx-memory)](https://www.npmjs.com/package/delx-memory)\n[![GitHub Release](https://img.shields.io/github/v/release/davidmosiah/delx-memory?label=release)](https://github.com/davidmosiah/delx-memory/releases/latest)\n[![npm downloads](https://img.shields.io/npm/dm/delx-memory)](https://www.npmjs.com/package/delx-memory)\n[![status: beta](https://img.shields.io/badge/status-beta-0EA5A3)](https://github.com/davidmosiah/delx-memory)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![node: >=20](https://img.shields.io/badge/node-%3E%3D20-green)](package.json)\n[![Verified Release Index](https://img.shields.io/badge/verified-release_index-0EA5A3)](https://github.com/davidmosiah/delx-wellness/blob/main/docs/release-index.md)\n\n## Why\n\nEvery 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.\n\n`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.\n\n- **15 tools** — discovery + handoff + batch ops + FTS5 search + mutations gated by intent.\n- SQLite at `~/.delx-memory/db.sqlite` (0700 dir, 0600 file).\n- **Secret-blocking**: refuses to store credential-shaped keys or values.\n- TTL support (lazy expiry on read).\n- Tags + prefix filters + FTS5 full-text search (bm25 ranking, stemming, diacritic folding; LIKE fallback if FTS5 is unavailable).\n- Mutations require `explicit_user_intent: true` so over-eager agents can't silently rewrite your context.\n- Zero telemetry. Zero phone-home. The file is yours.\n\n### Multi-agent namespaces\n\n```bash\n# Agent A\nDELX_MEMORY_NAMESPACE=claude npx -y delx-memory\n\n# Agent B (same machine, isolated keys)\nDELX_MEMORY_NAMESPACE=cursor npx -y delx-memory\n```\n\nKeys are stored as `namespace::key`. Omit the env var for a single global store (default).\n\n### Footprint / lightweight mode\n\n- **Default transport is `lite`**: tools-only MCP over stdio **without loading the MCP SDK** (biggest RSS win for always-on agents).\n- Full SDK surface (prompts + resources): `delx-memory --sdk` or `DELX_MEMORY_TRANSPORT=sdk`.\n- Optional HTTP: `delx-memory --http` (Express + SDK; still loopback by default).\n- `DELX_MEMORY_LEAN=1` applies to the **SDK** path only (skip prompts/resources).\n- `doctor --json` reports `rss_kb`. Dominant remaining cost is Node + native `better-sqlite3` (no embeddings).\n\nCommunity measurements (custom transport vs SDK) pointed at the SDK tree as the main overhead — see issue #7.\n\n\n## Install + run\n\n```bash\n# Run once (npx will download + boot)\nnpx -y delx-memory doctor\n\n# Or install globally\nnpm install -g delx-memory\ndelx-memory doctor\n```\n\nThe `doctor` command checks Node version, DB writability, and file permissions, then prints next steps.\n\n---\n\n## HTTP (v2 stateless)\n\nDefault is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:\n\n```bash\nnpx -y delx-memory --http\n# GET  http://127.0.0.1:3030/health\n# POST http://127.0.0.1:3030/mcp   (sessionless)\n```\n\nEnv: `DELX_MEMORY_HOST`, `DELX_MEMORY_PORT`, `DELX_MEMORY_TRANSPORT=http`.\n\n\n## Wire it into your MCP client\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"delx-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"delx-memory\"]\n    }\n  }\n}\n```\n\nThen restart Claude Desktop. See [`examples/claude-desktop.json`](./examples/claude-desktop.json).\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`. See [`examples/cursor.json`](./examples/cursor.json).\n\n### Hermes\n\nSee [`examples/hermes.md`](./examples/hermes.md).\n\n### OpenClaw\n\nSee [`examples/openclaw.md`](./examples/openclaw.md).\n\n### Codex CLI\n\nSee [`examples/codex.toml`](./examples/codex.toml).\n\n---\n\n## What makes it different (honest)\n\n| | delx-memory | Typical cloud memory | Graph memory MCP |\n|---|---|---|---|\n| Data leaves your machine | **No** | Yes | Usually no |\n| Multi-client same store | **Yes** (one SQLite) | Account-bound | Process-local |\n| Agent mutation safety | **`explicit_user_intent`** | Varies | Rare |\n| Secret storage | **Hard-refused** | Often allowed | Often allowed |\n| Default RSS path | **Lite (no MCP SDK)** | N/A | Full stack |\n| Multi-agent isolation | **`DELX_MEMORY_NAMESPACE`** | Tenants | Manual |\n| Search | **FTS5 bm25** | Embeddings (cost/leak) | Graph walk |\n\nNot a vector DB. Not a second brain SaaS. Local continuity for agents that already have a model.\n\n## Tools (15)\n\n\n### Session start\n\n| Tool | Purpose |\n|---|---|\n| `memory_handoff` | **One-call resume brief**: stats + recent keys (optional values). Prefer this at session start. |\n| `memory_agent_manifest` | Machine install/ops contract for agents. |\n| `memory_connection_status` / `memory_stats` | Readiness + store size. |\n| `memory_capabilities` / `memory_data_inventory` | Self-description for agents. |\n\n### Reads\n\n| Tool | Purpose |\n|---|---|\n| `memory_list` | Keys only; filters: `prefix`, `tag`, **`since`** (delta sync). |\n| `memory_get` / `memory_get_many` | Exact key or batch (max 50). |\n| `memory_search` | FTS5 bm25 (+ LIKE fallback). See [search quickstart](./examples/fts5-search.md). |\n\n### Mutations (require `explicit_user_intent: true`)\n\n| Tool | Purpose |\n|---|---|\n| `memory_set` / `memory_set_batch` | Upsert one key or up to 50 in one transaction. |\n| `memory_forget` / `memory_forget_by_tag` | Delete one key or by tag. |\n| `memory_export` | Dump JSON / JSONL / Markdown. |\n\nEvery 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.\n\n---\n\n## Privacy contract (read this)\n\n`delx-memory` is **NOT** a secrets manager. Use macOS Keychain / gnome-keyring / Windows Credential Manager for those.\n\n**What we refuse to store:**\n\n- **Keys** matching: `oauth`, `token`, `secret`, `password`, `cookie`, `refresh`, `api_key`, `api-key`, `apikey`, `bearer`, `credential`, `session_id` (case-insensitive).\n- **Values** matching credential shapes:\n  - JWT tokens (`eyJ…`)\n  - `Bearer <token>` headers\n  - Stripe `sk_live_…` / `sk_test_…`\n  - Slack `xoxb-…` / `xoxp-…` / etc.\n  - GitHub `github_pat_…` / `ghp_…` / `gho_…` / `ghs_…` / `ghr_…`\n  - OpenAI / Anthropic `sk-…` (with realistic length)\n  - AWS access keys `AKIA…`\n  - `Authorization: <scheme> <token>` strings\n- Nested objects are walked recursively — a nested field named `refresh_token` (even with an empty value) is rejected.\n\n**What stays local:**\n\n- The DB file lives at `~/.delx-memory/db.sqlite`.\n- Directory is created with mode `0700`; file with mode `0600`. (Best effort on Windows / WSL / non-POSIX filesystems.)\n- Nothing is uploaded. No telemetry. No phone-home.\n\n**What we do NOT promise:**\n\n- **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.\n- **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.\n- **No durability promise.** Back up `~/.delx-memory/db.sqlite` like any other dotfile if you care about losing it.\n\n---\n\n## Example session\n\n```\nagent> memory_stats({})\n→ { total_keys: 0, db_path: \"/Users/me/.delx-memory/db.sqlite\", … }\n\nuser> Remember that I prefer concise responses in pt-BR.\n\nagent> memory_set({\n  key: \"user_preferences\",\n  value: { language: \"pt-BR\", verbosity: \"concise\" },\n  tags: [\"profile\", \"preferences\"],\n  explicit_user_intent: true\n})\n→ { action: \"created\", key: \"user_preferences\", … }\n\n# … new chat, possibly different tool …\n\nagent> memory_list({ tag: \"preferences\" })\n→ [{ key: \"user_preferences\", updated_at: … }]\n\nagent> memory_get({ key: \"user_preferences\" })\n→ { found: true, value: { language: \"pt-BR\", verbosity: \"concise\" } }\n```\n\n---\n\n## Storage layout\n\n| | |\n|---|---|\n| Default path | `~/.delx-memory/db.sqlite` |\n| Override | `DELX_MEMORY_PATH` env var |\n| Directory mode | `0700` |\n| File mode | `0600` |\n| Schema | `memory(key PRIMARY KEY, value, created_at, updated_at, ttl_expires_at, tags, metadata)` |\n| Indexes | partial index on `ttl_expires_at`, plus `tags`, `updated_at` |\n| Per-value cap | 64 KB (JSON-serialized) |\n| Per-key cap | 512 chars |\n\n---\n\n## CLI\n\n```\ndelx-memory                Start MCP stdio server\ndelx-memory --http         Start local HTTP MCP server (127.0.0.1:3030)\ndelx-memory setup          Print MCP client config snippets\ndelx-memory setup --json   Print as JSON\ndelx-memory doctor         Health check + next steps\ndelx-memory doctor --json  Health check as JSON\ndelx-memory version        Print version\n```\n\n### Environment\n\n| Var | Default | Purpose |\n|---|---|---|\n| `DELX_MEMORY_PATH` | `~/.delx-memory/db.sqlite` | DB file location |\n| `DELX_MEMORY_TRANSPORT` | `stdio` | `stdio` or `http` |\n| `DELX_MEMORY_HOST` | `127.0.0.1` | HTTP host |\n| `DELX_MEMORY_PORT` | `3030` | HTTP port |\n| `DELX_MEMORY_ALLOWED_ORIGIN` | `http://HOST:PORT` | CORS origin |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/davidmosiah/delx-memory\ncd delx-memory\nnpm install\nnpm test         # typecheck + build + smoke + secret-detector + ttl + tag-delete + metadata\n```\n\nSee [`AGENTS.md`](./AGENTS.md) for repo conventions, [`SECURITY.md`](./SECURITY.md) for the security model and reporting policy, and [`CONTRIBUTING.md`](./CONTRIBUTING.md) for PR rules.\n\n---\n\n## License\n\nMIT © 2026 David Batista. [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Skill or MCP\n\nSame package, two doors. MCP registers tools on stdio/HTTP. The [skill](skill/SKILL.md) can drive the **same** tools through the CLI when the client has no MCP:\n\n```bash\nnpx -y delx-memory call memory_connection_status --json '{}'\n```\n\nCopy `skill/SKILL.md` into your agent skills dir.\n",
  "bytes": 10373,
  "sha": "5705aab31dafb794197693db3655e1dd57f2f9daa65ea8ddd3f1e68500c91783",
  "repo_slug": "davidmosiah/delx-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_delx_memory_104b7003/readme"
}