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 License: MIT 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)
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)

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 → .cursor/mcp.json (or VS Code equivalent — see examples/README.md).

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.

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

---

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

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. Changelog: CHANGELOG.md.

---

License

MIT © 2026 Przemyslaw Lusina — see LICENSE.