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:

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:

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

Configuration

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

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.