# 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`](docs/Architecture.md) — overall topology and module layout
- [`docs/Data-Model.md`](docs/Data-Model.md) — database schema, embeddings, and KG storage
- [`docs/API.md`](docs/API.md) — tool definitions, schemas, and transport contracts
- [`docs/MCP-Server-Guide.md`](docs/MCP-Server-Guide.md) — in-depth usage guide (single vs multi tool)

---

## Installation

```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.

### From npm (after publishing)

```sh
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

```sh
# 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:

```sh
# 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:

```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 `MCP_MULTI_TOOL=true` (in `.env` or the process environment). The server will register every tool described in [`docs/MCP-Server-Guide.md`](docs/MCP-Server-Guide.md).

---

## Cursor MCP Configuration

The published package is compatible with Cursor’s install link generator [[Cursor MCP install links](https://cursor.com/docs/context/mcp/install-links#generate-install-link)]:

```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 `--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](https://huggingface.co/docs/transformers.js/index)]. 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 |
| ------ | ----------- |
| `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`](docs/Operations.md) for deployment and scheduling guidance.

---

## Publishing Workflow

Follow the steps in [`docs/MCP-Server-Guide.md`](docs/MCP-Server-Guide.md) and [`CHANGELOG.md`](CHANGELOG.md), then run:

```sh
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.