MemorizedMCP-TS

Important: This MCP server has only been validated end-to-end with Cursor 2.0. Other IDEs or MCP hosts might require additional wiring or configuration changes. Contributions that broaden compatibility are very welcome!

MemorizedMCP-TS is a Bun + TypeScript implementation of the Memorized MCP server. It provides:

• Hybrid memory infrastructure (SQLite + Vectra) with multi-layer support
• Document intelligence with chunking, embeddings, FTS-backed search, and entity extraction
• A knowledge graph service that links entities, relationships, and contextual metadata
• A fully sandboxed run_code experience plus a rich multi-tool registry for discrete MCP calls
• Operational tooling: migrations, scheduled jobs, backup/restore, schema generation, and analytics

Key architectural docs:

• docs/Architecture.md — overall topology and module layout
• docs/Data-Model.md — database schema, embeddings, and KG storage
• docs/API.md — tool definitions, schemas, and transport contracts
• docs/MCP-Server-Guide.md — in-depth usage guide (single vs multi tool)

Installation

bun install
cp .env.example .env    # customise configuration if required

The server relies on Bun ≥ 1.3.0. Ensure the configured TRANSFORMER_MODEL is available locally or via the network, and create the DATA_ROOT directories if you plan to persist data.

From npm (after publishing)

npm install memorizedmcp-ts
bunx memorizedmcp-ts --multi-tool   # launches the published stdio server

CLI flags:

| Flag | Description | | ---- | ----------- | | --config <path> | Load an alternate .env file before bootstrapping | | --multi-tool | Force multi-tool registration (MCP_MULTI_TOOL=true) | | --single-tool | Force single-tool sandbox (MCP_MULTI_TOOL=false) | | --path <dir> | Override the root directory for SQLite + vector data (DATA_ROOT) | | --env KEY=VALUE | Inject arbitrary environment overrides (repeatable) | | --help | Print CLI usage |

All options map to the same environment variables used in self-hosted mode, so you can switch between single-tool and multi-tool behaviour without editing source code.

Tip: If Bun isn’t on your PATH, set BUN_BINARY=/custom/path/to/bun before running npx memorizedmcp-ts.

Quickstart

# Requires Bun (>=1.3.0) available on your PATH

# Launch the published MCP server (multi-tool mode)
npx -y memorizedmcp-ts --multi-tool

# or force single-tool sandbox
npx -y memorizedmcp-ts --single-tool

# or pin the storage root alongside other flags
npx -y memorizedmcp-ts --multi-tool --path "$PWD/.memorized"

For local development you can still run the source directly:

# Start in watch mode
bun run dev

# Or build + run the bundled output
bun run build
bun run start

Single-tool mode exposes a run_code tool with type-safe bindings:

const memory = await services.memory.addMemory({
  content: "User prefers dark mode",
  layer: "semantic",
  importance: 0.8,
});

const context = await services.knowledge.getEntityContext({
  entityId: "entity-id",
});

Toggle multi-tool mode by setting MCP_MULTI_TOOL=true (in .env or the process environment). The server will register every tool described in docs/MCP-Server-Guide.md.

Cursor MCP Configuration

The published package is compatible with Cursor’s install link generator [Cursor MCP install links]:

{
  "memorizedmcp-ts": {
    "command": "npx",
    "args": [
      "-y",
      "memorizedmcp-ts",
      "--",
      "--multi-tool"
    ],
    "env": {
      "LOG_LEVEL": "info",
      "TRANSFORMER_MODEL": "Xenova/all-MiniLM-L6-v2",
      "DATA_ROOT": "~/.memorizedmcp"
    }
  }
}

Switch between modes by replacing --multi-tool with --single-tool, or omit the flag to defer to .env defaults. Override storage with --path <dir> or provide additional overrides via repeated --env KEY=VALUE arguments.

Embedding Model Choices

The MCP server relies on a sentence embedding model for hybrid search. Transformers.js ships many compatible checkpoints [Transformers.js docs]. Pick the model that best matches your needs:

| Model | License | Dim | Notes | | ----- | ------- | --- | ----- | | Xenova/all-MiniLM-L6-v2 | Apache 2.0 (free) | 384 | Default in our examples. Fast, tiny (~80 MB), excellent for Bun/Node environments. | | Xenova/all-mpnet-base-v2 | Apache 2.0 (free) | 768 | Higher-quality English embeddings; ~3× the size and slower inference. | | Xenova/multilingual-MiniLM-L12-v2 | Apache 2.0 (free) | 384 | Balanced accuracy with multilingual coverage (50+ languages). |

For fully-managed / higher-accuracy options (with usage-based pricing), you can swap the embedding provider to Hugging Face Inference Endpoints or third-party APIs (e.g. OpenAI’s text-embedding-3-large). See src/services/embedding.ts for the integration point.

Update the environment variable accordingly:

TRANSFORMER_MODEL=Xenova/all-mpnet-base-v2

Available Scripts

| Script | Description | | ------ | ----------- | | bun run dev | Execute the entrypoint with file watching | | bun run start | Run the compiled bundle in dist/ | | bun run build | Bundle the server for distribution | | bun run build:types | Emit declaration files into dist/types/ | | bun run lint | Static analysis via Biome | | bun run format | Auto-format the codebase | | bun run test | Execute Vitest suites | | bun run migrate | Apply database migrations | | bun run generate-schemas | Produce JSON Schemas from Zod definitions | | bun run backup / bun run restore -- <dir> | Data snapshot + restore helpers | | bun run export:memories / import:memories | JSONL import/export utilities | | npm run prepare-release | Lint, test, build, emit declarations, regenerate schemas |

Configuration

The server reads configuration from .env (via dotenv) plus runtime overrides. Important keys:

| Variable | Description | Default | | -------- | ----------- | ------- | | LOG_LEVEL | Pino log level | info | | DATA_ROOT | Root for SQLite, backups, vectra indices | ./data | | SQLITE_URL | Path to SQLite database | ./data/sqlite/memorized.db | | TRANSFORMER_MODEL | Transformers.js model ID | hash (replace with a real model) | | MCP_MULTI_TOOL | Enable multi-tool registry | false | | MCP_ENABLE_PARENT_WATCHDOG | Kill the server if the launcher process disappears | true when MEMORIZEDMCP_PARENT_PID is provided, otherwise false | | MCP_ENABLE_STDIN_SHUTDOWN | Watch stdin closure as an additional shutdown signal | false (enable manually when your MCP host keeps stdin open) | | SINGLE_TOOL_TIMEOUT_MS | Sandbox timeout for run_code | 120000 | | CRON_* | Cron expressions for scheduled jobs | see .env.example |

Refer to docs/Operations.md for deployment and scheduling guidance.

Publishing Workflow

Follow the steps in docs/MCP-Server-Guide.md and CHANGELOG.md, then run:

npm run prepare-release
npm publish --access public --tag latest   # or beta/rc as appropriate

The prepare-release script executes linting, tests, bundling, type emission, and schema generation so the tarball includes everything required to run the MCP server.

Security & Hardening Checklist

• bun run test before every release
• Review cron schedules (CRON_*) and sandbox timeout (SINGLE_TOOL_TIMEOUT_MS)
• Store backups in secure storage and restrict filesystem permissions to DATA_ROOT
• Use a vetted TRANSFORMER_MODEL; pre-warm embeddings if offline

Compatibility Notes

• Fully tested with Cursor 2.0 (MCP host + IDE)
• Other MCP clients may require modified transport wiring or additional glue code (startMcpServer, tool registration)
• Report compatibility issues through GitHub issues so we can broaden out-of-the-box support

Contributing

1. Fork the repository and create a feature branch
2. Run bun run lint and bun run test before committing
3. Update documentation (README, MCP guide, CHANGELOG) as needed
4. Submit a PR describing how you tested the change (include IDE / MCP host details)

Thanks for using MemorizedMCP-TS! Complimentary feedback and feature requests are encouraged via GitHub issues or pull requests.