Skip to main content
Glama

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 Python License Version PyPI

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

๐Ÿค– This project is developed with AI โ€” designed, coded, tested, and documented in continuous collaboration with AI coding assistants from day one. Publicly open on GitHub for both human developers and autonomous AI agents.


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

  • Non-blocking by default โ€” incremental indexing runs in the background, eliminating IDE timeouts

New in v0.11.0: โฑ๏ธ Full background incremental indexing (index_changed_files), automatic crash/stale state recovery, GPU acceleration auto-detection for embeddings, and complete elimination of tool timeouts.

๐Ÿ“ See CHANGELOG.md for the full release history.


Related MCP server: aivectormemory

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.

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

  • File selection is shared with the indexer, so .indexignore keeps generated output (.next, dist) out of the graph โ€” see Ignore patterns

  • A build that runs out of files or time is reported as partial by find_symbol and health, never as "no symbols found"

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 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 (Non-Blocking)

index_changed_files re-indexes only what changed โ€” and cleans up after itself:

  • Non-blocking by default (background=True): returns immediately (< 15 ms) so AI assistants and IDEs never hit MCP tool timeouts.

  • A changed file's old chunks are deleted before the new ones land (renamed/removed symbols don't haunt search results).

  • Smart DB operations: skips redundant ChromaDB delete queries for new files, and tracks empty files without repeated indexing loops.

  • Chunks of deleted files are removed from ChromaDB, BM25, and 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 & Auto-Recovery

Both full (index_codebase) and incremental (index_changed_files) indexing run in dedicated daemon threads:

  • Returns instantly with status and file count while heavy embedding work proceeds in the background.

  • session_init auto-starts full background indexing when the index is missing or empty.

  • Poll get_index_progress() for a live progress bar, file counts, and ETA.

  • Self-Healing & Stale State Recovery: if the server process was killed or restarted mid-indexing, interrupted runs are automatically detected and reported as interrupted instead of remaining permanently stuck.

  • 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

# 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):

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

Other MCP clients (Claude Desktop / Zencoder / Cursor) โ€” mcp.json:

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

From source (development)

git clone https://github.com/mykolariabokon/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:

# 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

Context brief

get_context_brief โ€” ranked, budget-packed brief for a coding task: hybrid retrieval + 1-hop import graph + file skeletons + git recency; zero LLM calls (the "scout pyramid" layer 0)

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 (background by default), 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


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 with automatic GPU (CUDA) acceleration and multi-threaded CPU fallback

  • 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:

PROJECTMIND_MAX_FILE_SIZE_MB=5
PROJECTMIND_MAX_MEMORY_MB=200
PROJECTMIND_IMPORT_GRAPH_MAX_FILES=20000
PROJECTMIND_SYMBOL_GRAPH_MAX_FILES=8000
PROJECTMIND_SYMBOL_GRAPH_BUDGET_SECONDS=300
PROJECTMIND_TOOL_BUDGET_SECONDS=45
PROJECTMIND_MODEL_IDLE_UNLOAD_SECONDS=3600
PROJECTMIND_TOOL_PROFILE=full   # full (ั‚ะธะฟะพะฒะพ, 56 ั–ะฝัั‚ั€ัƒะผะตะฝั‚ั–ะฒ) | lean (16, ะฑะตะท ะดะตัั‚ั€ัƒะบั‚ะธะฒะฝะธั…)
PROJECTMIND_SLOW_SECTION_SECONDS=20   # ะฟะพั€ั–ะณ, ะฟั–ัะปั ัะบะพะณะพ ะทะฐะฒะธัะปัƒ ัะตะบั†ั–ัŽ ะฒะธะดะฝะพ ะฒ ะถัƒั€ะฝะฐะปั– (ะดะธะฒ. ยซะ›ั–ั‡ะธะปัŒะฝะธะบะธ ั‡ะฐััƒยป)

PROJECTMIND_TOOL_PROFILE=lean ั€ะตั”ัั‚ั€ัƒั” ะปะธัˆะต ัะดั€ะพ ั‡ะธั‚ะฐะฝะฝั ะน ะฟะพัˆัƒะบัƒ (search_codebase, find_symbol, get_symbol_relations, read_memory, search_memory, index_codebase ั‚ะฐ ั‰ะต ะบั–ะปัŒะบะฐ) ั– ะฒะบะพั€ะพั‡ัƒั” ั—ั…ะฝั– ะพะฟะธัะธ. ะžะฟะธั ั– ัั…ะตะผะฐ ะบะพะถะฝะพะณะพ ั–ะฝัั‚ั€ัƒะผะตะฝั‚ัƒ ะฟะปะฐั‚ัั‚ัŒ ั‚ะพะบะตะฝะฐะผะธ ะฝะฐ ะบะพะถะฝะต ะทะฒะตั€ะฝะตะฝะฝั ะผะพะดะตะปั–: ะฟะพะฒะฝะธะน ะฝะฐะฑั–ั€ โ‰ˆ 6 ั‚ะธั. ั‚ะพะบะตะฝั–ะฒ, lean โ‰ˆ 1,2 ั‚ะธั.

ะขั€ะฐะฝัะฟะพั€ั‚

ะ—ะฐ ะทะฐะผะพะฒั‡ัƒะฒะฐะฝะฝัะผ ัะตั€ะฒะตั€ ะณะพะฒะพั€ะธั‚ัŒ stdio. ะ”ะปั HTTP:

python mcp_server.py --transport streamable-http --host 127.0.0.1 --port 8000
# MCP-ะตะฝะดะฟะพั–ะฝั‚: http://127.0.0.1:8000/mcp

--host ั‚ะธะฟะพะฒะพ 127.0.0.1 (ะปะธัˆะต ะปะพะบะฐะปัŒะฝะธะน ะดะพัั‚ัƒะฟ). ะ†ะฝัˆะฐ ะฐะดั€ะตัะฐ ะฒั–ะดะบั€ะธะฒะฐั” ัะตั€ะฒะตั€ ะดะปั ะผะตั€ะตะถั–; ั€ะพะฑั–ั‚ัŒ ั†ะต ัะฒั–ะดะพะผะพ.

ะšะพั€ั–ะฝัŒ ะฟั€ะพั”ะบั‚ัƒ ะฒ http-ั€ะตะถะธะผั– ะทะฐั„ั–ะบัะพะฒะฐะฝะธะน. ะžะดะธะฝ ั‚ะตะฟะปะธะน ะฟั€ะพั†ะตั ะพะฑัะปัƒะณะพะฒัƒั” ะฒัั– ัะตัั–ั—, ะฐ ะบะพั€ั–ะฝัŒ ะฟั€ะพั”ะบั‚ัƒ ะฒ ะฝัŒะพะผัƒ ะพะดะธะฝ, ั‚ะพะถ ะนะพะณะพ ะทะฐะดะฐัŽั‚ัŒ ะฐั€ะณัƒะผะตะฝั‚ะพะผ --project-root <ั‚ะตะบะฐ> ั– ะฑั–ะปัŒัˆะต ะฝะต ะทะผั–ะฝัŽัŽั‚ัŒ:

projectmind-mcp --transport streamable-http --port 8000 --project-root /path/to/project

set_project_root ั– session_init(project_path=<ั–ะฝัˆะธะน>) ัƒ ั†ัŒะพะผัƒ ั€ะตะถะธะผั– ะฒั–ะดะผะพะฒะปััŽั‚ัŒ ะฟะพะฒั–ะดะพะผะปะตะฝะฝัะผ ั–ะท ะฝะฐะทะฒะพัŽ ะทะฐั„ั–ะบัะพะฒะฐะฝะพะณะพ ะบะพั€ะตะฝั (session_init ะท ั‚ะธะผ ัะฐะผะธะผ ะบะพั€ะตะฝะตะผ ะฟั€ะฐั†ัŽั”). ะะตั–ัะฝัƒัŽั‡ะธะน --project-root ะทัƒะฟะธะฝัั” ัั‚ะฐั€ั‚, ะฐ ะฝะต ะฟั–ะดะผั–ะฝัั”ั‚ัŒัั ะฟะพั‚ะพั‡ะฝะพัŽ ั‚ะตะบะพัŽ. ะ†ะฝัˆะพะผัƒ ะฟั€ะพั”ะบั‚ัƒ โ€” ะพะบั€ะตะผะธะน ัะตั€ะฒะตั€. ะฃ ั€ะตะถะธะผั– stdio ะฝั–ั‡ะพะณะพ ะฝะต ะทะผั–ะฝะธะปะพััŒ.

ะ›ั–ั‡ะธะปัŒะฝะธะบะธ ั‡ะฐััƒ

ะกะตั€ะฒะตั€ ะฟะธัˆะต ะฒ .ai/projectmind.log (ั€ั–ะฒะตะฝัŒ INFO) ั€ัะดะบะธ TIMING <ะผั–ั‚ะบะฐ> <ัะตะบัƒะฝะดะธ> thread=<ะฟะพั‚ั–ะบ>: ั–ะผะฟะพั€ั‚ะธ rank_bm25, symbol_graph, chromadb, sentence_transformers, torch, ะทะฐะฒะฐะฝั‚ะฐะถะตะฝะฝั ะน ะฟะพะฑัƒะดะพะฒัƒ BM25, ะทะฐะฒะฐะฝั‚ะฐะถะตะฝะฝั ะผะพะดะตะปั– ั‚ะฐ ะบะพะถะตะฝ ะฒะธะบะปะธะบ ั–ะฝัั‚ั€ัƒะผะตะฝั‚ะฐ (tool.<ั–ะผ'ั>, ะท ั‡ะฐัะพะผ ะพั‡ั–ะบัƒะฒะฐะฝะฝั ะฒั–ะปัŒะฝะพะณะพ ะฟะพั‚ะพะบัƒ queued=). ะฏะบั‰ะพ ัะตะบั†ั–ั ะฝะต ะทะฐะบั–ะฝั‡ัƒั”ั‚ัŒัั ะดะพะฒัˆะต ะทะฐ PROJECTMIND_SLOW_SECTION_SECONDS (ั‚ะธะฟะพะฒะพ 20 ั; ะฒะธะบะปะธะบะธ ั–ะฝัั‚ั€ัƒะผะตะฝั‚ั–ะฒ โ€” 60 ั), ัƒ ะถัƒั€ะฝะฐะป ั–ะดะต SLOW <ะผั–ั‚ะบะฐ> ั‰ะต ั‚ั€ะธะฒะฐั” โ€ฆ ะทั– ัั‚ะตะบะพะผ ะฟะพั‚ะพะบัƒ, ั‰ะพ ะฒ ะฝั–ะน ะทะฐัั‚ั€ัะณ, ั– ะฟะพะฒั‚ะพั€ัŽั”ั‚ัŒัั ั€ะฐะท ะฝะฐ 60 ั, ะดะพะบะธ ัะตะบั†ั–ั ะถะธะฒะฐ. ะขะฐะบ ะฒะธะดะฝะพ, ะดะต ัะฐะผะต ัั‚ะพั—ั‚ัŒ ะฟะตั€ัˆะธะน ั…ะพะปะพะดะฝะธะน ะฟะพัˆัƒะบ. ะŸั–ะดััƒะผะพะบ ะปั–ั‡ะธะปัŒะฝะธะบั–ะฒ ะฟะพะบะฐะทัƒั” health.

Ignore patterns

Create .indexignore in the project root (fallback: .ai/.indexignore), same substring syntax as shown in the generated default, plus globs like *.min.js. Patterns match the project-relative path, and a matching directory is pruned โ€” never descended into.

One file drives every consumer: the vector index, the BM25 corpus, the symbol graph and the manifest all select files through file_scanner.py. Excluding build output matters for more than disk space โ€” on a Next.js repo, app/.next held 6 409 of 7 354 parseable files and sorted first, so a symbol graph that ignored it burned its whole budget on minified bundles:

node_modules
.next
dist
*.min.js

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)
file_scanner.py         โ† single file-selection path (.indexignore + dir pruning) shared by all consumers
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.

ะขะตัั‚ะพะฒะต ัะตั€ะตะดะพะฒะธั‰ะต

ะขะตัั‚ะธ ะณะฐะฝัะนั‚ะต ัƒ ะฒะปะฐัะฝะพะผัƒ ะฒั–ั€ั‚ัƒะฐะปัŒะฝะพะผัƒ ัะตั€ะตะดะพะฒะธั‰ั–, ะฐ ะฝะต ะฒ ัะธัั‚ะตะผะฝะพะผัƒ Python (ัƒ ะฝัŒะพะผัƒ ะฝะตะผะฐั” ะทะฐะปะตะถะฝะพัั‚ะตะน). ะŸะพั‚ั€ั–ะฑะตะฝ Python 3.10โ€“3.12:

# Windows                              # macOS/Linux
py -3.12 -m venv .venv                 # python3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"     # .venv/bin/python -m pip install -e ".[dev]"

.venv\Scripts\python.exe -m pytest tests -q -p no:cacheprovider -o addopts=
.venv\Scripts\ruff check .
.venv\Scripts\black --check .

ะฆะต ั‚ะต ัะฐะผะต, ั‰ะพ ั€ะพะฑะธั‚ัŒ CI. ะ’ะตะบั‚ะพั€ะฝะธะน ัั‚ะตะบ [vector] ะดะปั ั‚ะตัั‚ั–ะฒ ะฝะต ะฟะพั‚ั€ั–ะฑะตะฝ: ะฑะตะท ะฝัŒะพะณะพ ัะตั€ะฒะตั€ ะฟั€ะฐั†ัŽั” ะฒ ั€ะตะถะธะผั– ะปะธัˆะต BM25, ั– ะฒะตััŒ ะฝะฐะฑั–ั€ (282 ั‚ะตัั‚ะธ) ะฟั€ะพั…ะพะดะธั‚ัŒ. ะฅะพะปะพะดะฝะธะน ัั‚ะฐั€ั‚ ัะตั€ะฒะตั€ะฐ ะทะฐะนะผะฐั” ะดะตััั‚ะบะธ ัะตะบัƒะฝะด, ั‚ะพะผัƒ ั‚ะตัั‚ะธ, ั‰ะพ ะทะฐะฟัƒัะบะฐัŽั‚ัŒ ัะฟั€ะฐะฒะถะฝั–ะน ะฟั€ะพั†ะตั, ะผะฐัŽั‚ัŒ ะฒะปะฐัะฝัƒ ัั‚ะตะปัŽ ั‡ะฐััƒ (@pytest.mark.timeout). ะฃ Python 3.12 venv ะฝะต ะผั–ัั‚ะธั‚ัŒ setuptools; ะฒั–ะฝ ะพะณะพะปะพัˆะตะฝะธะน ัƒ [dev], ะฑะพ ั‚ะตัั‚ ะบะพะปะตัะฐ ะทะฑะธั€ะฐั” ะฟะฐะบะตั‚ ะฑะตะท ั–ะทะพะปัั†ั–ั—.

CI runs ruff, black, mypy and the unit suite on Python 3.10โ€“3.12 (see .github/workflows/ci.yml).


License

MIT


Built with AI assistance โ€” used throughout development for coding, debugging, refactoring, and documentation.

Available Tools

56 tools
analyze_change_impactA
Predicts what breaks if you change a file. Uses import graph to find
direct dependents, transitive impact, and related tests to run.

Args:
    path: File path relative to project root.

Returns:
    Impact analysis with risk assessment and test recommendations.

Inputs: path (required). Returns: result

analyze_code_complexityB

Analyze cyclomatic complexity. mode='quick' (100 files) or 'deep' (1000).

Inputs: mode, target_path. Returns: result

analyze_code_qualityC

Pylint-based quality scan. mode='deep' raises max_files cap to 100.

Inputs: mode, max_files, target_path. Returns: result

analyze_project_structureD

Inputs: no named parameters. Returns: result

auto_update_memory_from_commitsD

Inputs: days, auto_summarize. Returns: result

check_dependenciesA
Analyzes project dependencies: versions, pinning strategy, duplicates, lock files.
Supports Python (pyproject.toml, requirements.txt), JS (package.json),
Go (go.mod), and Rust (Cargo.toml). No indexing required.

Returns:
    Dependency health report with version analysis.

Inputs: no named parameters. Returns: result

clear_memoryD

Inputs: keep_template. Returns: result

delete_memory_sectionD

Inputs: section_name (required). Returns: result

detect_project_conventionsA
Auto-detects project conventions: naming style, test patterns, frameworks,
linting/formatting tools, error handling, logging, architecture.
Does NOT require indexing. Results can be saved to memory for future reference.

Returns:
    Formatted conventions report.

Inputs: no named parameters. Returns: result

explore_directoryA
Lists files and subdirectories at the given path. Very fast, no indexing needed.
Use this to navigate the project tree level by level.

Args:
    path: Directory path relative to project root (use "." for root).
    depth: How many levels deep to show (1-3). Default 1.
    max_items: Maximum items to return. Default 100.

Returns:
    Tree-like listing of the directory contents.

Inputs: path, depth, max_items. Returns: result

extract_tech_stackD

Inputs: no named parameters. Returns: result

find_dependency_pathB
Finds the shortest dependency path between two files.

Args:
    from_file: Source file path (relative to project root)
    to_file: Target file path (relative to project root)
    max_depth: Maximum search depth (default 10)

Returns:
    Dependency chain from source to target, or message if no path found

Inputs: to_file (required), from_file (required), max_depth. Returns: result

find_symbolA
Finds where a function/class/method is defined using the AST symbol graph.
Works without the vector index (no embedding model needed).

Args:
    name: Symbol name โ€” exact or partial (case-insensitive).
    n_results: Max results (default 8).

Returns:
    Definitions with file:line plus caller/callee counts.

Inputs: name (required), n_results. Returns: result

find_todosA
Scans the codebase for TODO, FIXME, HACK, BUG, XXX comments.
Does NOT require indexing.

Args:
    tag: Optional filter by tag (e.g. "TODO", "FIXME"). None = all tags.

Returns:
    Summary and list of all TODO-like comments with file locations.

Inputs: tag. Returns: result

generate_project_summaryD

Inputs: no named parameters. Returns: result

get_annotationsA
Reads file annotations.

Args:
    path: Specific file to read the annotation for. Empty = coverage
        overview with all annotated files.

Returns:
    The annotation (or coverage summary) in Markdown.

Inputs: path. Returns: result

get_cache_statsB
Returns performance statistics for all caches.

Returns:
    Formatted string with cache statistics

Inputs: no named parameters. Returns: result

get_context_briefA
Deterministic CONTEXT BRIEF for a coding task โ€” the scout pyramid, layer 0.
Combines hybrid retrieval (vector/BM25), one-hop import-graph expansion,
file skeletons from the manifest and git recency into a ranked, budget-
packed markdown brief. Zero LLM calls, typically <500ms.

Args:
    task: The coding task in natural language.
    budget_tokens: Approximate token budget for the brief (default 4000).
    hint_files: File paths explicitly mentioned in the task (client-extracted).
    hint_symbols: Identifiers/symbols mentioned in the task (client-extracted).

Returns:
    Markdown brief: ranked files with symbols, import relations and
    top excerpts. Empty string when nothing relevant is indexed yet.

Inputs: task (required), hint_files, hint_symbols, budget_tokens. Returns: result

get_dependencies_with_depthA
Gets file dependencies up to specified depth in the import graph.

Args:
    file_path: File path relative to project root
    depth: How many levels deep to traverse (1-5, default 2)
    direction: "downstream" (what it imports) or "upstream" (what imports it)

Returns:
    List of files with their distance from the target file

Inputs: file_path (required), depth, direction. Returns: result

get_file_relationsA
Shows import relationships for a file: what it imports, what imports it,
and related test files. Built from static analysis (no indexing needed).

Args:
    path: File path relative to project root.

Returns:
    Import graph and impact assessment for the file.

Inputs: path (required). Returns: result

get_file_summaryA
Returns a lightweight summary of a file: size, imports, top-level definitions,
and the first N lines. Does NOT require indexing.

Args:
    path: File path relative to project root.
    max_lines: Max lines of content to include (default 50).

Returns:
    File metadata, structure, and preview.

Inputs: path (required), max_lines. Returns: result

get_index_progressA
Returns the current status of a background indexing operation started by
`index_codebase()` (with background=True, which is the default).

Statuses:
  - **idle**              โ€” no indexing job has been run yet
  - **scanning**          โ€” discovering indexable files (fast, ~1 s)
  - **initializing_model**โ€” loading SentenceTransformer model (30โ€“60 s first run)
  - **indexing**          โ€” embedding and storing file chunks
  - **finalizing**        โ€” flushing buffers and rebuilding BM25 index
  - **done**              โ€” indexing complete, search tools are ready
  - **error**             โ€” indexing failed (see `last_error` field)

Returns:
    Markdown-formatted progress report with file counts, percentage, and ETA.

Inputs: no named parameters. Returns: result

get_index_statsA

Returns statistics about the current vector store (number of chunks). This operation is very fast and doesn't trigger vector store initialization.

Inputs: no named parameters. Returns: result

get_module_clusterA
Finds files closely related to the target based on shared dependencies.
Uses Jaccard similarity to identify modules that work together.

Args:
    file_path: File path relative to project root
    similarity_threshold: Minimum similarity score 0.0-1.0 (default 0.3)
    max_cluster_size: Maximum number of related files (default 20)

Returns:
    List of related files sorted by similarity score

Inputs: file_path (required), max_cluster_size, similarity_threshold. Returns: result

get_project_overviewA
Returns a fast, lightweight overview of the project.
Does NOT require vector store or indexing.
Use this FIRST to understand the project before diving deeper.

Returns:
    Project name, tech stack, root directories, file type counts, config files.

Inputs: no named parameters. Returns: result

get_recent_changes_summaryD

Inputs: days. Returns: result

get_symbol_relationsA
Returns AST-level relations of a symbol from the symbol graph.

Args:
    symbol: Function/class/method name (bare, e.g. "UserService").
    relation: One of "usages" (default), "callers", "callees",
        "implementors", "subclasses", "bases", "info".

Returns:
    Related symbols with file:line, or full info for relation="info".

Inputs: symbol (required), relation. Returns: result

get_test_coverage_infoD

Inputs: no named parameters. Returns: result

healthA
Lightweight readiness check for the ProjectMind MCP server.

Reports: server version, active project root, memory file status, index status,
and whether the configured project is the MCP server's own directory.
Does NOT initialize the vector store or embeddings model.

Returns:
    Markdown-formatted health report.

Inputs: no named parameters. Returns: result

index_changed_filesA
Incrementally indexes only changed files since last indexing.

By default runs in background mode (non-blocking): detects changed files and
offloads embedding work to a background daemon thread, returning immediately.
Call `get_index_progress()` to monitor completion.

Args:
    background: If True (default), runs indexing in background and returns
                immediately. If False, blocks until complete (old behaviour).

Returns:
    Status message with indexing info

Inputs: background. Returns: result

index_codebaseA
Indexes the entire codebase for semantic search.

Limited to 5000 files per operation. For large codebases use index_changed_files() instead.

By default runs in **background** mode: returns immediately with a project
structure overview while the heavy embedding work continues in a daemon thread.
Call `get_index_progress()` to poll completion status.

Args:
    force: If True, clears existing index before indexing.
    background: If True (default), runs indexing in a background thread and
                returns immediately with a project overview. If False, blocks
                until indexing is fully complete (old behaviour โ€” may timeout
                on large codebases).

Returns:
    - background=True:  instant project structure overview + status line
    - background=False: final indexing stats string

Inputs: force, background. Returns: result

ingest_git_historyD

Inputs: limit. Returns: result

list_memory_versionsD

Inputs: no named parameters. Returns: result

list_unannotated_filesA
Lists code files that have no annotation (or a stale one), so you can
annotate them with save_annotation().

Recommended workflow: after finishing work on a file, save/refresh its
annotation; periodically run this tool and annotate the backlog โ€” that is
what makes natural-language search over this project accurate.

Args:
    limit: Max files per category (default 20).

Returns:
    Missing and stale annotation lists + coverage stats.

Inputs: limit. Returns: result

maintenance_runA

Synchronously run every self-healing task once. Returns a per-task report.

Inputs: no named parameters. Returns: result

maintenance_statusA

Reports the self-healing daemon's status, schedule, and recent history.

Inputs: no named parameters. Returns: result

project_onboardingA
One-command full project briefing. Runs overview + conventions + dependencies +
TODOs and compiles a comprehensive brief for onboarding a new developer or AI.
Results are saved to memory for future reference.

Returns:
    Complete project brief.

Inputs: no named parameters. Returns: result

prune_indexA
Aggressively prunes the vector index: drops orphan chunks and runs VACUUM.
Pass `force=True` to delete and rebuild the entire collection from scratch.

Inputs: force. Returns: result

queryA
Tier-aware project query. Cheaper than `search_codebase`.

Routes through L0 (manifest), then L1 (BM25), then L2 (vector embeddings),
escalating only when the previous tier yields a weak signal.

Args:
    text: Free-form query.
    intent: "overview" | "lookup" | "semantic" | "deep".
            - overview: L0 only โ€” paths and symbols. Always sub-second.
            - lookup:   L0 + L1 โ€” keyword/lexical search.
            - semantic: L0 + L1 + L2 โ€” pulls in embeddings if signal is weak.
            - deep:     L0 + L1 + L2 โ€” relaxed thresholds, more results.
    n_results: Final number of merged hits to return (1-50).

Inputs: text (required), intent, n_results. Returns: result

read_memoryB
Read project memory.

Args:
    max_lines: Maximum number of lines to return (default: 100).
               Set to None for full content. Use smaller values for quick summaries.

Returns:
    Memory content (possibly truncated)

Inputs: max_lines. Returns: result

read_memory_indexA
Returns just the section headings from `.ai/memory.md` plus a short tip.

Use this for an initial cheap scan; then call `read_memory_section(name)`
to expand only the section you actually need.

Inputs: no named parameters. Returns: result

read_memory_sectionA
Returns the contents of a single `## Heading` section from memory.md.

Args:
    section_name: Case-insensitive section heading (without leading `#`).
    max_lines: Max lines of body to return (truncated with a tip).

Inputs: section_name (required), max_lines. Returns: result

restore_memory_versionD

Inputs: timestamp (required). Returns: result

save_annotationA
Saves an AI-authored annotation (summary + keywords) for a source file.

Annotations make keyword search semantic WITHOUT embeddings: your summary
is indexed into BM25, so natural-language queries like "where is auth
handled" match it. Write annotations for files you have just read or
changed โ€” 1-2 sentences on what the file does and why it exists.

Args:
    path: File path relative to project root (or absolute inside it).
    summary: 1-3 sentences: purpose, key responsibilities, notable design.
    keywords: Comma-separated search terms a developer might query
        (synonyms, domain words not present in identifiers).

Returns:
    Confirmation with annotation coverage stats.

Inputs: path (required), summary (required), keywords. Returns: result

save_conventions_to_memoryB
Detects project conventions and saves them to memory.md automatically.
This persists conventions so AI assistants have context without re-scanning.

Returns:
    Confirmation with summary of what was saved.

Inputs: no named parameters. Returns: result

save_memory_versionD

Inputs: description. Returns: result

search_architectureB
Specialized search for understanding architecture. Finds:
- Core modules and entry points
- Module dependencies
- Configuration and setup
- Architectural patterns

Args:
    component: Component or module name (e.g., "auth", "database", "api")
    n_results: Number of results (default 10)

Returns:
    Architectural overview with dependency relationships

Inputs: component (required), n_results. Returns: result

search_codebaseD

Inputs: query (required), n_results. Returns: result

search_codebase_advancedD

Inputs: query (required), n_results, file_types, exclude_dirs, +1 more. Returns: result

search_for_errorsA
Specialized search for debugging errors. Automatically searches in:
- Error handlers and exception code
- Test files
- Similar error patterns
- Related git commits (if error recently introduced)

Args:
    error_text: The error message or exception type
    stacktrace: Optional stacktrace for better context
    n_results: Number of results per category (default 5)

Returns:
    Organized results focusing on debugging context

Inputs: error_text (required), n_results, stacktrace. Returns: result

search_for_featureB
Specialized search for understanding a feature. Automatically finds:
- Entry points and main implementations
- Configuration files
- Related tests
- Documentation

Args:
    feature_name: Name or description of the feature
    n_results: Number of results per category (default 10)

Returns:
    Organized results showing feature implementation structure

Inputs: feature_name (required), n_results. Returns: result

search_memoryA
Relevance-ranked memory retrieval. Returns the memory blocks most relevant
to `query` (scored by keyword overlap) instead of the head of memory.md.

Use this to pull targeted prior decisions/conventions/notes for the current
task without loading the whole memory file.

Args:
    query: Free-form text describing what you're looking for.
    n_results: Maximum number of memory blocks to return (default 5).

Returns:
    Markdown with the top matching memory blocks, or a hint if none match.

Inputs: query (required), n_results. Returns: result

search_with_dependenciesA
Searches codebase and optionally includes dependencies of matching files.
Combines semantic search with structural dependency analysis.

Args:
    query: Search query
    n_results: Number of semantic search results (default 5)
    include_deps: Whether to include dependencies (default True)
    depth: Dependency depth to include if include_deps=True (default 1)

Returns:
    Search results with optional dependency context

Inputs: query (required), depth, n_results, include_deps. Returns: result

session_initA
Single-call session bootstrap. Call this FIRST in every AI session.

Performs:
  1. Sets project root (if `project_path` is provided).
  2. Warns if the chosen root is the MCP server's own directory.
  3. Reads `.ai/memory.md` (only the index/headings โ€” full text on demand).
  4. Refreshes the lightweight L0 manifest.
  5. Reports vector-index status (without loading it).
  6. Starts the self-healing maintenance daemon.

The heavy vector store / embedding model is NEVER loaded here โ€” it is
lazily loaded only when a semantic query needs it. This keeps
`session_init` well under the MCP 30s tool timeout even on multi-GB
repositories.

Args:
    project_path: Absolute path to the target project. Leave empty to use
                  auto-detection (CWD + project markers).

Returns:
    Consolidated Markdown brief summarising project root, memory, and index state.

Inputs: project_path. Returns: result

set_project_rootA
Sets the target project root directory.
Call this FIRST when working with a project that is not auto-detected.

Args:
    path: Absolute path to the project root directory.

Returns:
    Confirmation message with the new project root.

Inputs: path (required). Returns: result

update_memoryD

Inputs: content (required), section. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    C2.4/5.0

    Scored across 56 tools

    Disambiguation2/5

    The search surface is heavily overlapping: search_codebase, search_codebase_advanced, query, search_with_dependencies, search_for_errors, search_for_feature, and search_architecture all retrieve project content with only subtle framing differences, and several of them have no description at all. Dependency analysis is similarly split across get_file_relations, get_dependencies_with_depth, find_dependency_path, get_module_cluster, and analyze_change_impact, and the memory surface has nine tools whose boundaries (read_memory vs read_memory_index vs read_memory_section vs search_memory) require careful reading to distinguish.

    Naming Consistency4/5

    Nearly everything is snake_case and mostly verb_noun (get_file_summary, find_symbol, save_annotation, index_changed_files), which makes the set scannable. Minor deviations exist in noun-only names like health, query, and maintenance_status, plus analyze_* vs get_* vs search_* prefixes that are not applied systematically.

    Tool Count2/5

    56 tools is far beyond what the domain needs, and a large fraction are undocumented aliases or near-duplicates (three memory read tools, four search variants, four dependency tools). Consolidating would make the set easier to select from rather than adding capability.

    Completeness4/5

    Coverage is genuinely broad: bootstrap, navigation, indexing with progress, tiered search, memory CRUD with versioning, maintenance, and analysis all exist. Gaps are modest โ€” no annotation update/delete, no doc for several tools, and no explicit repo-wide symbol listing โ€” but core lifecycles are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers