A Bun-powered MCP server that provides hybrid memory, document intelligence, and knowledge-graph tooling.
npm install memorizedmcp-tsImportant: 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)
---
``sh`
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.
`sh`
npm install memorizedmcp-ts
bunx memorizedmcp-ts --multi-tool # launches the published stdio server
CLI flags:
| Flag | Description |
| ---- | ----------- |
| --config | 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
| | 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.
---
`shRequires Bun (>=1.3.0) available on your PATH
For local development you can still run the source directly:
sh
Start in watch mode
bun run devOr build + run the bundled output
bun run build
bun run start
`Single-tool mode exposes a
tool with type-safe bindings:`ts
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
(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]:
`jsonc
{
"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
with --single-tool, or omit the flag to defer to .env defaults. Override storage with --path 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:
`bash
TRANSFORMER_MODEL=Xenova/all-mpnet-base-v2
`---
Available Scripts
| Script | Description |
| ------ | ----------- |
|
| 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 -- | 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 |docs/Operations.md for deployment and scheduling guidance.---
Publishing Workflow
docs/MCP-Server-Guide.md and CHANGELOG.md, then run:`sh
npm run prepare-release
npm publish --access public --tag latest # or beta/rc as appropriate
`The
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 ; 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 committingThanks for using MemorizedMCP-TS! Complimentary feedback and feature requests are encouraged via GitHub issues or pull requests.