Metadata-Version: 2.4
Name: projectmind-mcp
Version: 0.9.0
Summary: Give your AI coding assistant a brain: persistent memory, hybrid code search, AI-authored annotations, and an AST symbol graph — 100% local MCP server, no API keys.
Author: Mykola Riabokon
License: MIT
Project-URL: Homepage, https://github.com/Nik0lay1/project-mind-mcp
Project-URL: Repository, https://github.com/Nik0lay1/project-mind-mcp
Project-URL: Changelog, https://github.com/Nik0lay1/project-mind-mcp/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Nik0lay1/project-mind-mcp/issues
Keywords: mcp,model-context-protocol,code-search,claude,ai-memory,bm25,symbol-graph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.1.0
Requires-Dist: langchain-text-splitters>=0.0.1
Requires-Dist: GitPython>=3.1.0
Requires-Dist: radon>=6.0.0
Requires-Dist: pylint>=3.0.0
Requires-Dist: tree-sitter>=0.25.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter-java>=0.23.0
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.0
Requires-Dist: tree-sitter-ruby>=0.23.0
Requires-Dist: rank-bm25>=0.2.2
Provides-Extra: vector
Requires-Dist: chromadb>=1.0.0; extra == "vector"
Requires-Dist: sentence-transformers>=2.2.0; extra == "vector"
Requires-Dist: numpy<2.0,>=1.26; extra == "vector"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"

# ProjectMind MCP

> Give your AI coding assistant a brain. Persistent memory, semantic code search, a symbol-level call graph, and project intelligence — all running locally with no API keys required.

[![CI](https://github.com/Nik0lay1/project-mind-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Nik0lay1/project-mind-mcp/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Version](https://img.shields.io/badge/version-0.9.0-orange)
[![PyPI](https://img.shields.io/pypi/v/projectmind-mcp)](https://pypi.org/project/projectmind-mcp/)

**ProjectMind** is an open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that supercharges AI assistants like Claude, Zencoder, and Cursor with long-term project memory and intelligent codebase search.

> 🤖 **This project was built with AI** — designed, coded, debugged, and documented using AI-assisted development from day one.

---

## Why ProjectMind?

Every time you start a new AI session, your assistant forgets everything about your project. ProjectMind solves this:

- **No more re-explaining** your architecture every session — memory persists in `.ai/memory.md`
- **Semantic code search** that understands *what* code does, not just *what* it's named
- **Symbol graph** — ask "who calls this function?" and get exact file:line answers
- **Dependency graph analysis** to understand how modules connect
- **Works 100% locally** — your code never leaves your machine

**New in v0.9.0**: ✍️ AI-authored annotations (semantic search without embeddings), 📦 lightweight core with the vector stack as an optional `[vector]` extra, 🚀 one-line install from [PyPI](https://pypi.org/project/projectmind-mcp/).

📝 See [CHANGELOG.md](CHANGELOG.md) for the full release history.

---

## Features

### 🧠 Persistent Project Memory
Save architectural decisions, tech stack notes, and context that survives across sessions. The AI reads this at the start of every conversation.

Hierarchical memory access avoids dumping everything at once:
- `read_memory_index()` — section headings only (cheap)
- `read_memory_section(name)` — expand only the section you need
- `search_memory(query)` — **relevance-ranked** retrieval of the memory blocks most relevant to a task (keyword-scored), not just the head of the file

All memory I/O is UTF-8 — notes in any language survive round-trips on any OS.

### 🪜 Tiered Hierarchical Search
Queries escalate through tiers only when the previous one is insufficient — large repositories never trigger a cold load just to answer a path lookup.

| Tier | Engine | When used | Typical latency |
|---|---|---|---|
| **L0 Manifest** | `.ai/manifest.json` (paths + whole-file symbols) | always | < 50 ms |
| **L0 Annotations** | `.ai/annotations.json` (AI-written summaries) | always | < 5 ms |
| **L1 Symbol** | `.ai/symbol_graph.json` (AST symbol names) | when a prebuilt graph exists | < 10 ms |
| **L1 BM25** | `rank-bm25` lexical index (chunks + annotations) | when L0 is weak | ~ 100 ms |
| **L2 Vector** | ChromaDB + sentence-transformers (**optional** `[vector]` extra) | only on `intent='semantic'/'deep'` | first call ~ 30 s, then cached |

Use the unified `query(text, intent, n_results)` tool with one of:
- `overview` — L0 only (paths + top-level symbols)
- `lookup` — L0 + symbols + BM25 (keyword/lexical)
- `semantic` — escalates to embeddings if the lexical signal is weak
- `deep` — all tiers with relaxed thresholds

Hits from every tier are fused with **scale-invariant Reciprocal Rank Fusion** (normalized to 0..1), so no single tier can dominate the ranking by raw score magnitude — results corroborated across tiers float to the top.

### ✍️ AI-Authored Annotations — semantic search without embeddings
The killer pattern: your AI assistant *already understands your code* — so let it write the search index. As the assistant works on files, it saves 1-2 sentence summaries + keywords via `save_annotation()`. Annotations are indexed into BM25 and a dedicated query tier, so natural-language queries land on the right files with plain keyword search:

```
save_annotation("src/auth/session.py",
    "Session lifecycle: creates, refreshes and revokes OAuth sessions",
    keywords="login, oauth, token refresh")

query("where are sessions revoked?")  →  src/auth/session.py  (L0_annot tier)
```

- `list_unannotated_files()` — coverage report: files missing or with stale annotations (file changed since)
- `get_annotations(path)` — review what the index "knows" about a file
- Stored in human-readable `.ai/annotations.json`, UTF-8, atomic writes
- This is why the vector stack is now optional: a smart model + cheap precise tools beats a small embedding model guessing

### 🧬 Symbol Graph (AST-level call/inherit/implement graph)
tree-sitter parses every source file into a graph of *symbols*, not files. Symbols are keyed by qualified id (`path::Class.method`), so same-named symbols across files stay distinct.

- `find_symbol("UserService")` — where is it defined? (no embedding model needed, answers in milliseconds)
- `get_symbol_relations("save", relation="callers")` — who calls it, with file:line
- Relations: `callers`, `callees`, `implementors`, `subclasses`, `bases`, `usages`, `info`
- Inheritance extraction works across **Python, JS, TS, Java, Ruby**; builtin-call noise (`print`, `len`, `push`…) is filtered out
- The graph is rebuilt automatically by the background indexer and persisted to `.ai/symbol_graph.json`

### 🔍 Semantic Code Search
Search your codebase by *meaning*, not just text. Powered by a local `sentence-transformers` model — no OpenAI key needed.

```
"find authentication middleware"  →  finds auth code even if it's named differently
```

### 🌳 AST-Aware Chunking
Unlike naive text splitters that cut code in the middle of a function, ProjectMind uses [tree-sitter](https://tree-sitter.github.io) to parse source files into **exact syntax units**:

- Functions and methods are indexed as individual, self-contained chunks
- Class methods get a `# Class: ClassName` context prefix for better search relevance
- Rich metadata per chunk: `symbol_type`, `symbol_name`, `class_name`, `line_start`, `line_end`
- Supports: **Python, JavaScript, TypeScript, TSX, Java, Go, Rust, Ruby**
- Graceful fallback to text splitting for unsupported file types

### 🕸 Dependency Graph Intelligence
- Traverse import relationships up to 5 levels deep
- Find related files via shared dependency clustering
- Discover the shortest path between any two modules
- Identify entry points and orphaned modules
- **Monorepo-aware JS/TS resolution** — follows `tsconfig`/`jsconfig` path aliases (`@/...`) and workspace/package imports; multi-line, dynamic `import()` and side-effect imports are all detected
- **Python `src/`-layout & relative-import resolution** — absolute imports resolve through `src/`/`lib/` roots, dotted (`utils.helpers`) and relative (`.`/`..`) imports resolve to the right files
- **Cached import graph** (120 s TTL) with a precomputed reverse graph — impact/cluster analysis is O(E), not O(N²·E)

### ⚡ Instant Project Exploration (no indexing needed)
- `get_project_overview()` — manifest-first; tech stack, git info, file stats in < 1 second
- `explore_directory(path)` — browse project tree level by level
- `get_file_summary(path)` — imports, classes, functions, git history

### ⚡ Hybrid Search (BM25 + Vector)
Two search engines combined via **Reciprocal Rank Fusion (RRF)**:
- **BM25** catches exact keyword matches — finds `getUserById` when you type exactly that
- **Vector search** catches semantic matches — finds auth code even if named differently
- RRF merges both ranked lists for best-of-both-worlds results
- Automatic fallback to pure vector search when the BM25 index is not ready
- The BM25 index is persisted as **JSON** (`.ai/bm25_index.json`) — never pickle, so indexing a third-party repo can't execute untrusted input

### 🔄 True Incremental Indexing
`index_changed_files` re-indexes only what changed — and cleans up after itself:
- A changed file's **old chunks are deleted** before the new ones land (renamed/removed symbols don't haunt search results)
- Chunks of **deleted files** are removed from ChromaDB, BM25 and the metadata
- BM25 is patched **in memory** per file and rebuilt once — no full-database fetch per small change
- Failed writes are never silent: metadata isn't saved, so affected files retry on the next run

### 🏃 Background Indexing
`index_codebase()` returns instantly and indexes in a daemon thread; `session_init` auto-starts it when the index is missing. Poll `get_index_progress()` for a live progress bar with ETA. Switching projects mid-run cancels the old job safely — no cross-project contamination.

### 🩺 Self-Healing Maintenance Daemon
A background thread keeps the index lean without user intervention. State persists in `.ai/maintenance_state.json`.

| Task | Trigger | Action |
|---|---|---|
| `manifest_refresh` | every 5 min | rebuild L0 manifest if files changed |
| `stale_gc` | hourly | delete embeddings for files removed from disk |
| `db_compaction` | daily | `VACUUM` ChromaDB SQLite when > 200 MB |
| `log_truncate` | every 6 h | truncate `projectmind.log` when > 8 MB |
| `model_unload` | every 5 min | release `sentence-transformers` after 1 h idle (env-tunable) |
| `cache_pressure` | every minute | drop file/query caches when RSS > 500 MB |

Inspect with `maintenance_status()`; force a sync run with `maintenance_run()`; aggressively clean the index with `prune_index(force=True)`.

### 📊 Code Quality Metrics
Cyclomatic complexity, pylint scores, test coverage tracking — all queryable via MCP tools.
Both `analyze_code_complexity` and `analyze_code_quality` accept `mode='quick'` (default, fast) or `mode='deep'` (wider scan). pylint runs in a subprocess with a wall-clock budget, so these tools return partial results instead of timing out.

### ⚡ Lazy `session_init` (no 30 s timeouts)
`session_init` never loads the embedding model; it returns the project root + manifest + memory index in well under a second even on multi-GB repositories. The vector store is loaded only when an `intent='semantic'` or `'deep'` query actually needs it.

---

## Quick Start

### One-liner (recommended)

```bash
# Claude Code
claude mcp add --scope user Memory -- uvx projectmind-mcp
```

The default install is **lightweight** (a few MB — BM25 keyword search, AI annotations, symbol graph, memory). To add the optional embedding/vector tier (~500 MB, fully local):

```bash
claude mcp add --scope user Memory -- uvx --from "projectmind-mcp[vector]" projectmind-mcp
```

**Other MCP clients (Claude Desktop / Zencoder / Cursor)** — `mcp.json`:

```json
{
  "mcpServers": {
    "Memory": {
      "command": "uvx",
      "args": ["projectmind-mcp"]
    }
  }
}
```

### From source (development)

```bash
git clone https://github.com/Nik0lay1/project-mind-mcp.git
cd project-mind-mcp
python -m venv .venv

# Windows                          # macOS/Linux
.venv\Scripts\pip install -e ".[vector,dev]"   # .venv/bin/pip install -e ".[vector,dev]"
```

Then point your MCP client at `.venv/Scripts/python.exe mcp_server.py` (or use the `projectmind-mcp` console script from the venv).

### 3. Bootstrap a session

Ask the AI (once per session):
```
Memory__session_init(project_path="<absolute path to your project>")
```

If the index doesn't exist yet, background indexing starts automatically — check `Memory__get_index_progress()`. For manual full re-indexing of large projects:

```bash
# Windows
.venv\Scripts\python.exe run_index.py

# macOS/Linux
.venv/bin/python run_index.py
```

---

## Available Tools (45+)

| Category | Tools |
|---|---|
| **Session** | `session_init`, `health`, `set_project_root` |
| **Memory** | `read_memory`, `read_memory_index`, `read_memory_section`, `search_memory`, `update_memory`, `clear_memory`, `save_memory_version` |
| **Search** | `query` (tier-aware), `search_codebase`, `search_for_feature`, `search_architecture`, `search_for_errors`, `search_with_dependencies` |
| **Annotations** | `save_annotation`, `get_annotations`, `list_unannotated_files` |
| **Symbols** | `find_symbol`, `get_symbol_relations` (callers / callees / implementors / subclasses / bases / usages) |
| **Exploration** | `get_project_overview`, `explore_directory`, `get_file_summary` |
| **Dependencies** | `get_file_relations`, `get_dependencies_with_depth`, `get_module_cluster`, `find_dependency_path`, `analyze_change_impact` |
| **Indexing** | `index_codebase` (background by default), `index_changed_files`, `get_index_progress`, `get_index_stats`, `prune_index` |
| **Git** | `ingest_git_history`, `get_recent_changes_summary`, `auto_update_memory_from_commits` |
| **Quality** | `analyze_code_complexity`, `analyze_code_quality`, `get_test_coverage_info` |
| **Maintenance** | `maintenance_status`, `maintenance_run` |
| **Project** | `detect_project_conventions`, `generate_project_summary` |

Full reference: [docs/api/tools-reference.md](docs/api/tools-reference.md)

---

## How It Works

```
Your Project
     │
     ▼
ProjectMind MCP Server
     │
     ├── .ai/memory.md                ← persistent notes & decisions (UTF-8)
     ├── .ai/annotations.json         ← AI-written file summaries (search tier)
     ├── .ai/manifest.json            ← L0: paths, symbols, modules (≤200 KB)
     ├── .ai/symbol_graph.json        ← L1: AST call/inherit/implement graph
     ├── .ai/bm25_index.json          ← L1: lexical index (JSON, not pickle)
     ├── .ai/vector_store/            ← L2: ChromaDB embeddings (local)
     ├── .ai/index_metadata.json      ← tracks changed files (mtime)
     ├── .ai/index_progress.json      ← live background-indexing progress
     ├── .ai/maintenance_state.json   ← self-healing daemon schedule
     └── .ai/.indexignore             ← per-project ignore patterns
     │
     ▼
AI Assistant (Claude / Zencoder / Cursor)
```

**Embedding model**: `flax-sentence-embeddings/st-codesearch-distilroberta-base`
- Trained specifically on code (CodeSearchNet dataset)
- ~130 MB, runs fully locally on CPU
- No API keys, no data sent anywhere

**Search pipeline**: manifest + symbol graph + BM25 (keyword) + ChromaDB (semantic) → Reciprocal Rank Fusion → top-N results

---

## Requirements

- Python 3.10 – 3.12
- ~500 MB disk (model + dependencies)
- Works on Windows, macOS, Linux

---

## Configuration

All settings in `config.py`:

| Setting | Default | Description |
|---|---|---|
| `MODEL_NAME` | `flax-sentence-embeddings/st-codesearch-distilroberta-base` | Embedding model |
| `CHUNK_SIZE` | `1500` | Characters per chunk |
| `MAX_FILE_SIZE_MB` | `10` | Skip files larger than this |
| `MAX_MEMORY_MB` | `100` | Memory limit for indexing batch |
| `IMPORT_GRAPH_MAX_FILES` | `8000` | Max files scanned when building the import graph |
| `TOOL_SOFT_BUDGET_SECONDS` | `20` | Wall-clock budget for analysis tools — they return partial results instead of timing out |

Override via environment variables:
```bash
PROJECTMIND_MAX_FILE_SIZE_MB=5
PROJECTMIND_MAX_MEMORY_MB=200
PROJECTMIND_IMPORT_GRAPH_MAX_FILES=20000
PROJECTMIND_SYMBOL_GRAPH_MAX_FILES=8000
PROJECTMIND_TOOL_BUDGET_SECONDS=45
PROJECTMIND_MODEL_IDLE_UNLOAD_SECONDS=3600
```

Custom ignore patterns: create `.indexignore` in the project root (fallback: `.ai/.indexignore`), same substring syntax as shown in the generated default.

---

## Project Structure

```
mcp_server.py           ← all MCP tool definitions
config.py               ← configuration + path validation
manifest.py             ← L0 lightweight project manifest
symbol_graph.py         ← AST symbol graph (call/inherit/implement), format v3
query_router.py         ← tier-aware query() router (L0 → L1_symbol → L1 → L2)
maintenance.py          ← self-healing background daemon
background_indexer.py   ← non-blocking indexing with live progress
vector_store_manager.py ← ChromaDB wrapper + hybrid search (L2)
bm25_index.py           ← BM25 keyword index + RRF fusion (L1, JSON persistence)
codebase_indexer.py     ← file scanning & AST-aware chunking
ast_splitter.py         ← tree-sitter parser (9 languages, thread-safe)
code_intelligence.py    ← import graph, complexity analysis, cached graphs
memory_manager.py       ← persistent memory read/write (UTF-8, atomic)
incremental_indexing.py ← change tracking (mtime) + atomic writes
context.py              ← dependency injection (thread-safe lazy init)
run_index.py            ← helper script for manual re-indexing
```

---

## Contributing

Issues and PRs are welcome. This is an open project — built in the open, improved in the open.

```bash
pip install -e ".[dev]"
pytest tests/
ruff check .
```

CI runs ruff, black, mypy and the unit suite on Python 3.10–3.12 (see [.github/workflows/ci.yml](.github/workflows/ci.yml)).

---

## License

MIT

---

*Built with AI assistance — used throughout development for coding, debugging, refactoring, and documentation.*
