# Local Memory MCP

Persistent, local semantic memory for tools that speak the Model Context Protocol. A connected client can save notes, context, and preferences during one session and recall them later by meaning rather than exact wording. Everything is kept in a single SQLite file on your machine, and embeddings are computed locally on the CPU.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg?logo=python&logoColor=white)
![Tauri](https://img.shields.io/badge/desktop-Tauri-24c8db.svg?logo=tauri&logoColor=white)

## Overview

The server runs over stdio and exposes three tools: one to store text, one to search it semantically, and one to clear a namespace. Stored text is embedded with a small sentence-transformer model and indexed for vector search with [sqlite-vec](https://github.com/asg017/sqlite-vec). After a one-time model download, no network connection is needed.

An optional desktop application is included for inspecting and managing what has been stored.

## Features

- Three tools over MCP: `store_memory`, `search_memory`, `wipe_project_memories`.
- Local embeddings with `all-MiniLM-L6-v2` (384 dimensions).
- Vector search backed by sqlite-vec in a single SQLite database.
- Per-project namespaces through a `project_tag` field.
- An importance score for each memory that decays with age and rises each time the memory is recalled.
- A blacklist that stops chosen terms, such as `.env` or `password`, from being stored or written to the log.
- An optional desktop dashboard with an activity feed, a memory table, and privacy controls.

## How it works

```mermaid
flowchart LR
    C["MCP client"] -- "stdio" --> S["server.py (FastMCP)"]
    S --> E["memory_engine.py"]
    E -- "embeddings" --> M["all-MiniLM-L6-v2 (local CPU)"]
    E -- "read / write (WAL)" --> DB[("memory.db: SQLite + sqlite-vec")]
    UI["Desktop dashboard"] -- "read / delete / blacklist" --> DB
```

The server and the dashboard share one SQLite file in WAL mode. The dashboard can read and manage memory while the server is writing to it, and neither side blocks the other.

## Requirements

- Python 3.11 or newer
- [uv](https://docs.astral.sh/uv/)
- For the desktop app: [Rust](https://rustup.rs/), [Node.js](https://nodejs.org/), and a C/C++ toolchain. On Windows that means the Visual Studio C++ Build Tools. See the [Tauri prerequisites](https://tauri.app/start/prerequisites/) for other platforms.

## Running the server

```bash
git clone https://github.com/AQuietRiver/local-memory-mcp.git
cd local-memory-mcp
uv sync
uv run python server.py
```

The first run downloads the embedding model (about 90 MB) and caches it. Later runs do not touch the network.

## Connecting a client

Add a server entry to your MCP client's configuration file, using an absolute path:

```json
{
  "mcpServers": {
    "local-memory": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/local-memory-mcp", "python", "server.py"]
    }
  }
}
```

Restart the client and the three tools become available.

## Tools

| Tool | Signature | Purpose |
|------|-----------|---------|
| `store_memory` | `(content, metadata="", project_tag="global")` | Embed and save a piece of text. Rejected if it matches a blacklisted term. |
| `search_memory` | `(query, project_tag="global", limit=5)` | Rank stored text by semantic similarity to the query. |
| `wipe_project_memories` | `(project_tag)` | Delete every memory in a namespace. |

Each tool has a docstring that the client reads to decide when to call it.

## Desktop dashboard

A companion application for watching and managing the memory bank. It sits in the system tray and opens to three panels.

| Panel | Function |
|-------|----------|
| Activity Feed | A chronological log of tool calls, showing the tool, the project, the text passed, and the result. |
| Memory Vault | A searchable table of stored memories with their tag, timestamp, and importance score, plus a per-row delete. |
| Privacy Center | A control to erase all memory at once, and a manager for blacklisted terms. |

Deleting from the dashboard removes the embedding from disk as well as the row, not just the metadata.

### Building

```bash
cd tauri-ui
npm install
npm run dev      # development window with hot reload
npm run build    # standalone installer and executable
```

The Windows vector extension (`vec0.dll`) is included under `tauri-ui/src-tauri` so the app can load sqlite-vec and remove embeddings. For macOS or Linux, place the matching `vec0.dylib` or `vec0.so` from the [sqlite-vec releases](https://github.com/asg017/sqlite-vec/releases) in the same directory and update the `resources` entry in `tauri.conf.json`.

## Scoring and blacklist

The importance score is `100 * 0.5^(age_days / 30)` plus a small capped bonus for each recall, clamped to the range 0 to 100. Recency is the main factor; recalling a memory slows its decay. The Python engine and the dashboard compute the score the same way.

The blacklist is checked before any text is embedded. Comparison is case-insensitive and substring-based. A match is rejected, nothing is stored, and the activity log keeps a redacted record instead of the original text.

## Data location

All data lives in a single file at `~/.config/local_memory_mcp/memory.db`. There is no separate index or cache to manage.

## Project layout

```
local-memory-mcp/
├── memory_engine.py     # database and embedding engine
├── server.py            # FastMCP server exposing the tools
├── pyproject.toml       # packaging and dependencies
├── test_smoke.py        # engine and tool-layer tests
├── test_features.py     # blacklist, scoring, activity, and wipe tests
└── tauri-ui/            # optional desktop dashboard
    ├── src/             # frontend (HTML, CSS, JavaScript)
    └── src-tauri/       # Rust backend (tray and read/write database layer)
```

## Testing

```bash
uv run python test_smoke.py
uv run python test_features.py

cd tauri-ui/src-tauri
cargo test
```

## License

MIT. See [LICENSE](LICENSE).