{"id":51194840,"url":"https://github.com/davidmosiah/delx-memory","last_synced_at":"2026-06-27T19:02:48.234Z","repository":{"id":359965557,"uuid":"1247799476","full_name":"davidmosiah/delx-memory","owner":"davidmosiah","description":"Local-first persistent memory layer for AI agents. SQLite-backed, MCP-compatible, cross-agent. Privacy: secret-blocking writes, file-only storage.","archived":false,"fork":false,"pushed_at":"2026-06-27T11:53:58.000Z","size":225,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T13:05:03.192Z","etag":null,"topics":["agent-memory","agent-ready","ai-agent-tools","ai-agents","anthropic","claude-desktop","cursor","local-first","mcp","mcp-server","model-context-protocol","persistent-memory","sqlite","wearable-data"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/delx-memory","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidmosiah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T19:50:48.000Z","updated_at":"2026-06-27T11:54:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/davidmosiah/delx-memory","commit_stats":null,"previous_names":["davidmosiah/delx-memory"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/davidmosiah/delx-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fdelx-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fdelx-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fdelx-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fdelx-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidmosiah","download_url":"https://codeload.github.com/davidmosiah/delx-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fdelx-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34864431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-ready","ai-agent-tools","ai-agents","anthropic","claude-desktop","cursor","local-first","mcp","mcp-server","model-context-protocol","persistent-memory","sqlite","wearable-data"],"created_at":"2026-06-27T19:02:47.464Z","updated_at":"2026-06-27T19:02:48.228Z","avatar_url":"https://github.com/davidmosiah.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# delx-memory\n\n\u003e 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: alpha](https://img.shields.io/badge/status-alpha-orange)](https://github.com/davidmosiah/delx-memory)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![node: \u003e=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- 8 MCP tools — 4 read-only, 4 mutating.\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---\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## 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## The 8 tools\n\n### Reads (always safe — call without confirmation)\n\n| Tool | Purpose |\n|---|---|\n| `memory_stats` | High-level: total keys, DB size, oldest entry, DB path. **Start here on any session.** |\n| `memory_list` | List keys (not values) with optional prefix or tag filter. |\n| `memory_get` | Exact key lookup. Returns value + timestamps + tags + metadata. |\n| `memory_search` | FTS5 full-text search across keys, values and tags — bm25 relevance ranking, stemming, diacritic folding, prefix matching; LIKE fallback if FTS5 is missing. Returns snippets. See the [search quickstart](./examples/fts5-search.md). |\n\n### Mutations (require `explicit_user_intent: true`)\n\n| Tool | Purpose |\n|---|---|\n| `memory_set` | Upsert a key. Rejects credential-shaped keys/values. |\n| `memory_forget` | Delete one key. Idempotent. |\n| `memory_forget_by_tag` | Bulk-delete every entry carrying a given tag. |\n| `memory_export` | Dump store as JSON / JSONL / Markdown, with optional `since` / `until` window. |\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 \u003ctoken\u003e` 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: \u003cscheme\u003e \u003ctoken\u003e` 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\u003e memory_stats({})\n→ { total_keys: 0, db_path: \"/Users/me/.delx-memory/db.sqlite\", … }\n\nuser\u003e Remember that I prefer concise responses in pt-BR.\n\nagent\u003e 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\u003e memory_list({ tag: \"preferences\" })\n→ [{ key: \"user_preferences\", updated_at: … }]\n\nagent\u003e 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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmosiah%2Fdelx-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidmosiah%2Fdelx-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmosiah%2Fdelx-memory/lists"}