# Unsloth session memory MCP

A read-only MCP server that lets Unsloth Studio retrieve earlier local chat sessions from its SQLite database.

It exposes four tools:

- `list_sessions`
- `get_session`
- `recall_previous_session`
- `search_sessions`

Only user and assistant text is returned. System messages, tool output, reasoning blocks, images, audio, and attachments are excluded. Common API-key and token patterns are redacted from returned text.

## Requirements

- Unsloth Desktop or Studio with history in `~/.unsloth/studio/studio.db`
- Node.js 22.5 or newer

## Add it to Unsloth with a config file

Download [examples/unsloth-npx-import.json](examples/unsloth-npx-import.json), then in Unsloth Studio:

1. Open a chat and select **MCP** beside the composer.
2. Select **Manage MCP servers**.
3. Select **Import config** and choose the downloaded JSON file.
4. Enable **Unsloth session memory** and select **Test connection**.

The config runs this command:

```bash
npx --yes github:kashyaparun25/unsloth-session-memory-mcp --stdio
```

If Unsloth reports that local MCP commands are disabled, use the local HTTP option below. Source builds can set `UNSLOTH_STUDIO_ALLOW_STDIO_MCP=1`; packaged Desktop builds may control this option internally.

## Add it as a command

Create a local MCP server in Unsloth and enter:

```text
npx --yes github:kashyaparun25/unsloth-session-memory-mcp --stdio
```

No repository checkout is required. `npx` downloads the public GitHub repository and starts the stdio server.

## Add it as a local URL

Clone the repository and start the HTTP transport:

```bash
git clone https://github.com/kashyaparun25/unsloth-session-memory-mcp.git
cd unsloth-session-memory-mcp
npm install
npm run build
node dist/cli.js --http --config examples/config.json
```

Enter `http://127.0.0.1:7331/mcp` in Unsloth, or import [examples/unsloth-http-import.json](examples/unsloth-http-import.json).

A hosted website URL cannot read the Unsloth database on your Mac. Run this server on the same Mac as Unsloth unless you deliberately copy or mount the database elsewhere.

For access from another machine, use TLS and a bearer token:

```bash
UNSLOTH_MEMORY_TOKEN='replace-with-a-random-value' \
node dist/cli.js --http --host 0.0.0.0 --port 7331 --config examples/config.json
```

Then configure the MCP client to send `Authorization: Bearer <your token>`. The server refuses a non-loopback HTTP binding without a token.

## Configuration

Copy [examples/config.json](examples/config.json) to change the database path, response limits, permitted message roles, or redaction behavior.

Environment overrides:

- `UNSLOTH_MEMORY_CONFIG`: config-file path
- `UNSLOTH_STUDIO_DB_PATH`: database-path override
- `UNSLOTH_MEMORY_TOKEN`: HTTP bearer token

Verify the configuration without returning chat content:

```bash
npx --yes github:kashyaparun25/unsloth-session-memory-mcp --check
```

The process opens SQLite in read-only mode and also enables `PRAGMA query_only`.

## Use it in a chat

Ask Unsloth:

```text
Use recall_previous_session to retrieve the previous chat, then tell me what we decided.
```

For precise retrieval, call `list_sessions` and then `get_session` with the selected thread ID.

Unsloth does not automatically give a third-party MCP server the current hidden thread ID. If the model does not supply `currentThreadId`, `recall_previous_session` treats the newest stored thread as the current chat and returns the second newest eligible thread. Supplying `currentThreadId` and `projectId` avoids that assumption.

## Develop and test

```bash
npm install
npm run check
npm run build
npm test
```

See [SECURITY.md](SECURITY.md) before exposing the HTTP transport beyond localhost.

## License

MIT