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.