memdb

A SQLite-backed MCP memory server with local workspace storage, full-text search (FTS5), and knowledge graph capabilities for AI assistants.

Overview

memdb is a Model Context Protocol (MCP) server that provides persistent memory storage for AI assistants. It uses Node.js's native node:sqlite module to store memories locally with SHA-256 content deduplication, FTS5 full-text search, and a knowledge graph of typed relationships between memories. Communication happens over stdio transport.

Related MCP server: agent-memory

Key Features

• Persistent local storage — SQLite database stored in the workspace (.memdb/memory.db by default) with WAL mode for performance

• Full-text search — FTS5-powered content and tag search with BM25 relevance scoring and recency boosting

• Knowledge graph — Directed, typed relationships between memories with recursive graph traversal (recall)

• SHA-256 deduplication — Content-addressed storage prevents duplicate memories automatically

• Batch operations — Store or delete up to 50 memories in a single call with partial success support

• Memory classification — Categorize memories by type (general, fact, plan, decision, reflection, lesson, error, gradient) and importance (0–10)

• Protocol safety — Custom stdio transport that rejects JSON-RPC batch requests, protocol version guard, and tool execution timeouts

Tech Stack

Architecture

┌─────────────────────────────────────────────┐
│                   Client                    │
└──────────────────┬──────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼──────────────────────────┐
│ 1. BatchRejectingStdioServerTransport       │  ← Rejects JSON-RPC batch arrays
│ 2. ProtocolVersionGuardTransport            │  ← Validates protocol version
│ 3. McpServer (MCP SDK)                      │  ← Tool/resource registration
│ 4. Tool handlers with timeout + error wrap  │  ← Zod validation, abort signals
│ 5. Core layer (db, search, relationships)   │  ← SQLite + FTS5 + knowledge graph
└─────────────────────────────────────────────┘

Repository Structure

memdb/
├── src/
│   ├── core/               # Database and business logic
│   │   ├── db.ts            # SQLite connection, schema, WAL, statement cache
│   │   ├── memory-read.ts   # Get, delete, stats operations
│   │   ├── memory-write.ts  # Store, update with SHA-256 deduplication
│   │   ├── relationships.ts # Knowledge graph edge operations
│   │   ├── search.ts        # FTS5 search and graph traversal (recall)
│   │   └── abort.ts         # Abort signal utilities
│   ├── index.ts             # Server entrypoint, stdio transport, shutdown
│   ├── tools.ts             # MCP tool registration with timeout handling
│   ├── schemas.ts           # Zod schemas for all 12 tools
│   ├── types.ts             # TypeScript interfaces
│   ├── config.ts            # Environment variable configuration
│   ├── logger.ts            # Logging (console.error, never stdout)
│   ├── stdio-transport.ts   # Custom stdio transport with batch rejection
│   ├── protocol-version-guard.ts  # Protocol version validation
│   ├── instructions.md      # User-facing instructions (MCP resource)
│   ├── async-context.ts     # AsyncLocalStorage for tool context
│   └── error-utils.ts       # Error message extraction
├── tests/                   # node:test runner tests
├── scripts/                 # Build & task automation
├── assets/                  # Logo/icon assets
├── .github/workflows/       # CI/CD (npm publish on release)
├── package.json
├── tsconfig.json
└── eslint.config.mjs

Requirements

• Node.js ≥ 24 — required for the native node:sqlite module

Quickstart

The fastest way to start using memdb is via npx:

npx -y @j0hanz/memdb@latest

Add to your MCP client configuration:

{
  "mcpServers": {
    "memdb": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memdb@latest"]
    }
  }
}

Installation

NPX (recommended)

No installation needed — runs the latest version directly:

npx -y @j0hanz/memdb@latest

Global Install

npm install -g @j0hanz/memdb
memdb

From Source

git clone https://github.com/j0hanz/memdb-mcp-server.git
cd memdb-mcp-server
npm install
npm run build
npm start

Configuration

Environment Variables

Environment variables can be set via a .env file when using npm run dev:run, or passed directly to the process.

Database Location

By default, memdb creates the database at .memdb/memory.db relative to the working directory. The directory is created automatically if it doesn't exist.

Usage

memdb communicates exclusively over stdio transport. Start the server and connect via any MCP-compatible client:

# Direct
node dist/index.js

# Via npx
npx -y @j0hanz/memdb@latest

# With custom database path
MEMDB_PATH=/path/to/my.db npx -y @j0hanz/memdb@latest

MCP Surface

Tools

memdb exposes 12 tools organized into memory management, search, knowledge graph, and diagnostics.

store_memory

Store a new memory with tags. Idempotent — storing the same content returns the existing hash.

Returns:

{
  "ok": true,
  "result": {
    "id": 1,
    "hash": "a1b2c3d4e5f6...",
    "isNew": true
  }
}

store_memories

Store multiple memories in a single batch operation (1–50 items). Supports partial success.

Returns:

{
  "ok": true,
  "result": {
    "results": [
      { "ok": true, "index": 0, "hash": "a1b2...", "isNew": true },
      { "ok": false, "index": 1, "error": "Tag must not contain whitespace" }
    ],
    "succeeded": 1,
    "failed": 1
  }
}

get_memory

Retrieve a single memory by its SHA-256 hash.

Returns:

{
  "ok": true,
  "result": {
    "id": 1,
    "content": "TypeScript uses structural typing",
    "summary": null,
    "tags": ["typescript", "types"],
    "importance": 5,
    "memory_type": "fact",
    "created_at": "2025-01-15 10:30:00",
    "accessed_at": "2025-01-15 10:30:00",
    "hash": "a1b2c3d4..."
  }
}

update_memory

Update memory content. Returns the new hash since content changes affect the hash. Idempotent.

Returns:

{
  "ok": true,
  "result": {
    "updated": true,
    "oldHash": "a1b2c3d4...",
    "newHash": "e5f6g7h8..."
  }
}

delete_memory

Delete a single memory by hash. Destructive operation.

Returns:

{ "ok": true, "result": { "deleted": true } }

delete_memories

Delete multiple memories by hash in a single batch operation (1–50 hashes). Supports partial success. Destructive.

Returns:

{
  "ok": true,
  "result": {
    "results": [
      { "hash": "a1b2...", "deleted": true },
      { "hash": "c3d4...", "deleted": false, "error": "Memory not found" }
    ],
    "succeeded": 1,
    "failed": 1
  }
}

search_memories

Search memories by content and tags using FTS5 full-text search with BM25 relevance scoring and recency boosting. Read-only.

Returns:

{
  "ok": true,
  "result": [
    {
      "id": 1,
      "content": "TypeScript uses structural typing",
      "tags": ["typescript", "types"],
      "importance": 5,
      "memory_type": "fact",
      "relevance": 0.85,
      "hash": "a1b2c3d4...",
      "created_at": "2025-01-15 10:30:00",
      "accessed_at": "2025-01-15 10:30:00"
    }
  ]
}

recall

Search for memories and traverse relationships to return a connected graph cluster. Use for deeper context retrieval that follows knowledge graph connections. Read-only.

Returns:

{
  "ok": true,
  "result": {
    "memories": [{ "id": 1, "content": "...", "relevance": 0.9, "...": "..." }],
    "relationships": [
      {
        "id": 1,
        "from_hash": "a1b2...",
        "to_hash": "c3d4...",
        "relation_type": "related_to",
        "created_at": "2025-01-15 10:30:00"
      }
    ],
    "depth": 1
  }
}

create_relationship

Link two memories with a typed, directed relationship. Idempotent — creating the same relationship returns the existing ID.

Returns:

{ "ok": true, "result": { "id": 1, "isNew": true } }

get_relationships

Get all relationships for a memory. Read-only.

Returns:

{
  "ok": true,
  "result": [
    {
      "id": 1,
      "from_hash": "a1b2...",
      "to_hash": "c3d4...",
      "relation_type": "depends_on",
      "created_at": "2025-01-15 10:30:00"
    }
  ]
}

delete_relationship

Remove a relationship between two memories. Destructive.

Returns:

{ "ok": true, "result": { "deleted": true } }

memory_stats

Database statistics and health. No parameters required. Read-only.

Returns:

{
  "ok": true,
  "result": {
    "memoryCount": 42,
    "tagCount": 15,
    "oldestMemory": "2025-01-01 00:00:00",
    "newestMemory": "2025-02-09 12:00:00"
  }
}

Resources

Prompts

None.

Client Configuration Examples

Add to your VS Code settings.json or use the one-click install buttons above:

{
  "mcp": {
    "servers": {
      "memdb": {
        "command": "npx",
        "args": ["-y", "@j0hanz/memdb@latest"]
      }
    }
  }
}

With environment variables:

{
  "mcp": {
    "servers": {
      "memdb": {
        "command": "npx",
        "args": ["-y", "@j0hanz/memdb@latest"],
        "env": {
          "MEMDB_PATH": "${workspaceFolder}/.memdb/memory.db",
          "MEMDB_LOG_LEVEL": "warn"
        }
      }
    }
  }
}

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "memdb": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memdb@latest"]
    }
  }
}

Or manually add to Cursor MCP settings:

{
  "mcpServers": {
    "memdb": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memdb@latest"]
    }
  }
}

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "memdb": {
      "command": "npx",
      "args": ["-y", "@j0hanz/memdb@latest"]
    }
  }
}

Security

• stdio hygiene — All logging is sent to stderr via console.error(). No non-MCP output is written to stdout, preventing JSON-RPC corruption.

• Batch request rejection — JSON-RPC batch arrays are explicitly rejected by the custom BatchRejectingStdioServerTransport with proper error responses per MCP spec (≥ 2025-06-18).

• Protocol version guard — Unsupported protocol versions are rejected at the transport layer before reaching tool handlers. The connection is closed after sending the error.

• Input validation — All tool inputs are validated via Zod strict schemas at the MCP boundary. Null bytes in environment variables are detected and rejected.

• Database safety — SQLite defensive mode is enabled, foreign key constraints are enforced, and the allowExtension option is set to false.

Development Workflow

Prerequisites

• Node.js ≥ 24

Install dependencies

npm install

Scripts

Build and Release

The project publishes to npm via a GitHub Actions workflow triggered on GitHub Releases:

1. Checkout → Setup Node.js 20 → Install dependencies

2. Lint → Type-check → Test → Coverage

3. Build → Extract version from release tag → Publish to npm with trusted publishing (OIDC)

See .github/workflows/publish.yml for the full pipeline.

Troubleshooting

node:sqlite not found

You are running Node.js < 24. The native node:sqlite module requires Node.js ≥ 24.

node --version  # Must be >= 24.0.0

Database locked errors

The server uses SQLite WAL mode. If you see locked errors, ensure no external tools are accessing .memdb/memory.db while the server is running.

FTS5 errors

If you get errors mentioning fts5 or no such module, ensure your Node.js binary includes the standard SQLite FTS5 extension (it should by default in Node.js ≥ 24).

Debugging with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

stdout corruption (stdio mode)

If your MCP client receives malformed responses, ensure no middleware or debugging tools are writing to stdout. memdb routes all logging to stderr.

Contributing

Contributions are welcome! Please ensure your changes pass all checks before submitting:

npm run lint && npm run type-check && npm run build && npm test

License

MIT