# MemoryStar

**Local semantic memory MCP server for AI coding agents** — Cursor, VS Code / GitHub Copilot, and OpenCode.

MemoryStar gives your agent persistent, searchable project knowledge: architecture notes, file symbols, git history, progress tracking, and a knowledge graph — all stored locally (SQLite + ChromaDB).

**Repository:** [github.com/ussdeveloper/memory-star](https://github.com/ussdeveloper/memory-star)  
**License:** [MIT](LICENSE)  
**Author:** Przemyslaw Lusina

---

## Features

- **33 MCP tools** — save, search (FTS5 + vectors), link, archive, sync, and more
- **Per-file tracking** — SHA256 change detection, symbol extraction, descriptions
- **Knowledge graph** — relationships between memories (`depends_on`, `implements`, …)
- **Auto-sync** — background watcher + Cursor hooks after every edit
- **Web dashboard** — graph view, browse, semantic search (`http://127.0.0.1:7988`)
- **Windows installer** — one-click setup into any project folder
- **Privacy-first** — all data stays on your machine

---

## Quick start

### Option A — Install into your project (Windows)

1. Download or build `dist/MemoryStar-Setup.exe` (see [dist/README.md](dist/README.md))
2. Requires **Python 3.10–3.13** on PATH
3. Run the installer → pick project folder → pick IDE
4. Open project in IDE → **Reload Window**
5. Dashboard: http://127.0.0.1:7988

Installed layout:

```
your-project/
  .memorystar/          # server, venv, database
    data/               # SQLite + ChromaDB
    server.py
    .venv/
  .cursor/mcp.json      # or .vscode/mcp.json
  AGENTS.md
```

### Option B — Run from source (this repo)

```bash
git clone https://github.com/ussdeveloper/memory-star.git
cd memory-star
python -m venv .venv
.venv/Scripts/activate          # Windows
pip install -r requirements.txt
```

Copy [examples/dev-cursor.mcp.json](examples/dev-cursor.mcp.json) → `.cursor/mcp.json` (or VS Code equivalent — see [examples/README.md](examples/README.md)).

```bash
python server.py
```

---

## MCP tools (overview)

| Category | Tools |
|----------|--------|
| **Core** | `memory_save`, `memory_load`, `memory_update`, `memory_search`, `memory_archive` |
| **Graph** | `memory_link`, `memory_get_links` |
| **Files** | `memory_update_file_structure`, `memory_get_file_info`, `memory_list_files` |
| **Hooks** | `memory_check_for_changes`, `memory_process_changes` |
| **Orchestration** | `memory_sync_project`, `memory_suggest_scan` |
| **Git** | `memory_git_history` |
| **Watcher** | `memory_start_watcher`, `memory_stop_watcher` |
| **Progress** | `memory_track_progress`, `memory_progress_update`, `memory_get_progress` |
| **Changelog** | `memory_changelog_add`, `memory_changelog_get`, `memory_changelog_trends` |
| **Maintenance** | `memory_clear`, `memory_restore`, `memory_list_backups`, `memory_stats`, `memory_trends` |

Full tool reference is in the server docstring and [AGENTS.md](AGENTS.md).

### Agent workflow (recommended)

```
Session start  →  memory_suggest_scan(project_path=".")
After edits    →  memory_check_for_changes → memory_process_changes (if changed)
Save knowledge →  memory_save(key=..., scope="architecture|api|decisions|...")
Before task    →  memory_search(query=..., mode="combined")
```

---

## Architecture

```
Agent (MCP client)
    │
    ├── stdio ── MemoryStar MCP Server (server.py)
    │              ├── SQLite + FTS5
    │              ├── ChromaDB (vectors)
    │              ├── file_structure + memory_links
    │
    ├── HTTP :9120 ── Webhook (watcher, context monitor)
    │
    └── HTTP :7988 ── UI dashboard
```

---

## Configuration

Key environment variables (set in `.cursor/mcp.json` or `.vscode/mcp.json`):

| Variable | Description | Default |
|----------|-------------|---------|
| `MEMORYSTAR_DATA_DIR` | Database directory | `./data` (dev) or `.memorystar/data` (install) |
| `MEMORYSTAR_PROJECT_PATH` | Workspace root to watch | — |
| `MEMORYSTAR_AUTO_SYNC` | Sync on MCP startup | `1` |
| `MEMORYSTAR_AUTO_WATCH` | Background file watcher | `1` |
| `MEMORYSTAR_UI_PORT` | Dashboard port | `7988` |
| `MEMORYSTAR_ENABLE_*` | Per-feature toggles | all `1` |

See [README configuration section](#feature-toggles) below for full list.

### Feature toggles

| Flag | Tools |
|------|-------|
| `MEMORYSTAR_ENABLE_CORE` | save, load, update, search |
| `MEMORYSTAR_ENABLE_FILE_STRUCTURE` | file scan, symbols, change hooks |
| `MEMORYSTAR_ENABLE_SYNC` | `memory_sync_project` |
| `MEMORYSTAR_ENABLE_WATCHER` | start/stop watcher |

All flags documented in [AGENTS.md](AGENTS.md).

---

## UI dashboard

Open **http://127.0.0.1:7988** when the MCP server is running.

- **Browse** — memories, files, scopes, project tree
- **Graph** — force-directed knowledge graph
- **Search** — semantic + full-text
- **Guide** — built-in agent instructions

---

## Project structure

```
memory-star/
  server.py           MCP server + webhook + UI
  database.py           SQLite + ChromaDB layer
  config.py             Environment configuration
  ui.html               Dashboard (single file)
  requirements.txt
  AGENTS.md             Agent instructions (copy to projects)
  examples/             MCP config templates
  dist/                 Windows installer + build scripts
  .cursor/hooks/        Cursor hook scripts
```

---

## Building the Windows installer

```powershell
cd dist
.\build.ps1
```

Produces `MemoryStar-Setup.exe` and `MemoryStar-Windows.zip`.

---

## Scopes

Use meaningful `scope` values when saving memories:

`architecture` · `api` · `dependencies` · `patterns` · `decisions` · `bugs` · `notes` · `file-structure` · `git-history`

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Changelog: [CHANGELOG.md](CHANGELOG.md).

---

## License

MIT © 2026 Przemyslaw Lusina — see [LICENSE](LICENSE).