memdb

A SQLite-backed MCP memory server (on-disk by default, in-memory optional).

One-Click Install

Features

| Feature | Description | | :---------------- | :---------------------------------------------------------------- | | Memory Storage | Store text memories with tags, importance, and type | | Full-Text Search | FTS5-backed tokenized search with relevance ranking | | Graph Connections | Link memories and traverse relationships | | Stats | Memory, tag, and relationship counts + activity range | | Local Privacy | All data stored locally in SQLite (.memdb/memory.db by default) |

Quick Start

VS Code / Cursor

Add this to your mcpServers configuration:

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

Installation

NPX (Recommended)

npx -y @j0hanz/memdb@latest

Global Installation

npm install -g @j0hanz/memdb

From Source

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

Configuration

The server uses a local SQLite database at <cwd>/.memdb/memory.db by default. The path is resolved to an absolute path unless you use :memory:.

Environment Variables

• MEMDB_PATH: Override the database path (:memory: for in-memory).
• MEMDB_LOG_LEVEL: info, warn, or error (default: info).
• MEMDB_SHUTDOWN_TIMEOUT: Shutdown timeout in ms (1000-60000, default: 5000).

CLI Flags

• --db <path>: Override the database path.
• --memory: Use in-memory database (:memory:).
• --log-level <level>: info, warn, or error.
• --shutdown-timeout <ms>: Shutdown timeout in ms (1000-60000).

Precedence: CLI flags > environment variables > defaults.

Tool Response Format

All tools return structured JSON in structuredContent. For backwards compatibility, the first content item is a JSON string that matches structuredContent.

Success (structuredContent):

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

Error (structuredContent):

{
  "ok": false,
  "error": {
    "code": "E_CODE",
    "message": "Human-readable message"
  }
}

Error responses also set isError: true on the top-level tool result.

Example content[0].text:

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

Tools

store_memory

Store a new memory with optional tags and metadata.

| Parameter | Type | Required | Default | Description | | :----------- | :------- | :------- | :-------- | :----------------------------------------- | | content | string | Yes | - | The content of the memory (1-100000 chars) | | tags | string[] | No | - | Tags (max 100, each 1-50 chars) | | importance | number | No | 0 | Importance score (0-10) | | memoryType | string | No | general | Type of memory (1-50 chars) |

Returns: { id, hash, isNew }

Notes:

• Content is deduplicated by MD5 hash. Storing the same content again returns the same hash with isNew: false.

search_memories

Full-text search with filters.

| Parameter | Type | Required | Default | Description | | :------------- | :------- | :------- | :------ | :-------------------------------- | | query | string | Yes | - | Search query (1-1000 chars) | | limit | number | No | 10 | Maximum number of results (1-100) | | offset | number | No | 0 | Pagination offset (0-1000) | | tags | string[] | No | - | Filter by tags (max 50) | | minRelevance | number | No | - | Minimum relevance score (0-1) |

Returns: Array of search results (Memory + relevance).

get_memory

Retrieve a specific memory by its hash.

| Parameter | Type | Required | Default | Description | | :-------- | :----- | :------- | :------ | :------------------ | | hash | string | Yes | - | MD5 hash (32 chars) |

Returns: Memory.

delete_memory

Delete a memory by its hash.

| Parameter | Type | Required | Default | Description | | :-------- | :----- | :------- | :------ | :------------------ | | hash | string | Yes | - | MD5 hash (32 chars) |

Returns: { deleted: true }.

link_memories

Create a relationship between two memories.

| Parameter | Type | Required | Default | Description | | :------------- | :----- | :------- | :------ | :----------------------------------- | | fromHash | string | Yes | - | Hash of the source memory (32 chars) | | toHash | string | Yes | - | Hash of the target memory (32 chars) | | relationType | string | Yes | - | Type of relationship (1-50 chars) |

Returns: { linked: true }.

Notes:

• Linking the same relation again is a no-op (idempotent).
• Returns an error if either memory hash does not exist.

get_related

Get memories related to a given memory.

| Parameter | Type | Required | Default | Description | | :------------- | :----- | :------- | :--------- | :----------------------------- | | hash | string | Yes | - | Hash of the memory (32 chars) | | relationType | string | No | - | Filter by relationship type | | depth | number | No | 1 | Traversal depth (1-3) | | direction | string | No | outgoing | outgoing, incoming, both |

Returns: Array of related memories (Memory + relation_type, depth).

memory_stats

Get database statistics and memory type breakdown.

No parameters required.

Returns: { memoryCount, relationshipCount, tagCount, memoryTypes, oldestMemory, newestMemory }.

update_memory

Update memory metadata (content cannot be changed).

| Parameter | Type | Required | Default | Description | | :----------- | :------- | :------- | :------ | :------------------------------------------ | | hash | string | Yes | - | MD5 hash (32 chars) | | importance | number | No | - | New importance score (0-10) | | memoryType | string | No | - | New memory type (1-50 chars) | | tags | string[] | No | - | Replace all tags (max 100, each 1-50 chars) | | addTags | string[] | No | - | Tags to add (max 100, each 1-50 chars) | | removeTags | string[] | No | - | Tags to remove (max 100, each 1-50 chars) |

Returns: { updated: true, hash }.

Memory Fields

All memory-shaped responses include:

• id: integer ID
• content: original content string
• summary: optional summary (currently unset by tools)
• importance: integer 0-10
• memory_type: string
• created_at: timestamp string
• accessed_at: timestamp string
• hash: MD5 hash

Client Configuration

Add to your settings.json or mcpServers config:

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

Add to your claude_desktop_config.json:

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

1. Go to Cursor Settings > Features > MCP
2. Click + Add New MCP Server
3. Name: memdb
4. Type: command
5. Command: npx -y @j0hanz/memdb@latest

Limits & Constraints

| Constraint | Value | Description | | :---------------------------- | :------------ | :---------------------------------------------------------------------------- | | Max content length | 100,000 chars | Maximum characters in memory content | | Max query length | 1,000 chars | Maximum characters in search query | | Max search terms | 50 | Maximum whitespace-separated terms per query | | Max search results | 100 | Maximum results returned from search_memories | | Default search limit | 10 | Default limit for search_memories | | Max search offset | 1,000 | Maximum offset for search_memories | | Max tags per memory | 100 | Maximum number of tags when storing a memory | | Max tag length | 50 chars | Maximum characters per tag | | Max tags in search filter | 50 | Maximum tags when filtering search results | | Max related memories | 1,000 | Maximum results from get_related queries | | Max traversal depth | 3 | Maximum depth for relationship traversal | | Importance range | 0-10 | Allowed range for importance | | Min relevance range | 0-1 | Allowed range for minRelevance | | Hash length | 32 chars | MD5 hash length | | Search mode | Tokenized OR | Whitespace-split terms are quoted and OR'ed; FTS5 operators are not supported |

Notes

• Content deduplication: Memories are deduplicated using MD5 hashes.
• Search errors: If FTS5 is unavailable, search_memories returns an error indicating the index is missing. Invalid query syntax returns an error with details.
• Search tokenization: Queries are split on whitespace (max 50 terms); whitespace-only queries are rejected.
• Tag behavior: Tags are de-duplicated per memory; exceeding tag limits throws an error.
• Bidirectional depth: get_related with direction: "both" caps traversal depth at 2.
• Local storage: All data is stored locally in .memdb/memory.db unless :memory: is used.

Development

Prerequisites

• Node.js >= 22.0.0 (required for node:sqlite)

Scripts

| Command | Description | | :------------------------ | :----------------------------------------- | | npm run clean | Remove dist/ | | npm run build | Compile TypeScript to dist/ | | npm run dev | Run in development mode with watch | | npm run start | Run compiled server (node dist/index.js) | | npm run test | Run tests | | npm run test:coverage | Run tests with coverage | | npm run lint | Run ESLint | | npm run format | Format code with Prettier | | npm run format:check | Check code formatting | | npm run type-check | TypeScript type checking | | npm run type-check:test | Type-check tests only | | npm run duplication | Run duplication report (jscpd) | | npm run inspector | Run MCP inspector |

Project Structure

src/
|-- index.ts          # Server entry point (stdio transport)
|-- core/             # SQLite setup + memory CRUD/search/relations
|   |-- database.ts   # DB init + schema sync
|   |-- memory-create.ts
|   |-- memory-read.ts
|   |-- memory-search.ts
|   |-- memory-relations.ts
|   |-- memory-updates.ts
|   |-- memory-stats.ts
|-- tools/            # Tool registration + handlers
|   |-- definitions/  # Tool metadata + handlers
|-- schemas/          # Zod input/output schemas
|   |-- inputs.ts
|   |-- outputs.ts
|-- lib/              # Error/response helpers
|-- types/            # TypeScript types
`-- utils/            # Config + logger

tests/
`-- *.test.ts         # Node.js test runner tests

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.