ProjectMind MCP
Provides tools to ingest and analyze git history, summarize recent changes, and automatically update project memory from commits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ProjectMind MCP search for authentication middleware in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.mdSemantic 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 needsearch_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 |
| always | < 50 ms |
L0 Annotations |
| always | < 5 ms |
L1 Symbol |
| when a prebuilt graph exists | < 10 ms |
L1 BM25 |
| when L0 is weak | ~ 100 ms |
L2 Vector | ChromaDB + sentence-transformers (optional | only on | 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 weakdeepโ 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 fileStored in human-readable
.ai/annotations.json, UTF-8, atomic writesThis 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:lineRelations:
callers,callees,implementors,subclasses,bases,usages,infoInheritance extraction works across Python, JS, TS, Java, Ruby; builtin-call noise (
print,len,pushโฆ) is filtered outThe graph is rebuilt automatically by the background indexer and persisted to
.ai/symbol_graph.jsonFile selection is shared with the indexer, so
.indexignorekeeps generated output (.next,dist) out of the graph โ see Ignore patternsA build that runs out of files or time is reported as partial by
find_symbolandhealth, never as "no symbols found"
๐ 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 to parse source files into exact syntax units:
Functions and methods are indexed as individual, self-contained chunks
Class methods get a
# Class: ClassNamecontext prefix for better search relevanceRich metadata per chunk:
symbol_type,symbol_name,class_name,line_start,line_endSupports: 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/jsconfigpath aliases (@/...) and workspace/package imports; multi-line, dynamicimport()and side-effect imports are all detectedPython
src/-layout & relative-import resolution โ absolute imports resolve throughsrc//lib/roots, dotted (utils.helpers) and relative (./..) imports resolve to the right filesCached 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 secondexplore_directory(path)โ browse project tree level by levelget_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
getUserByIdwhen you type exactly thatVector 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_initauto-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
interruptedinstead 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 |
| every 5 min | rebuild L0 manifest if files changed |
| hourly | delete embeddings for files removed from disk |
| daily |
|
| every 6 h | truncate |
| every 5 min | release |
| 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)
# Claude Code
claude mcp add --scope user Memory -- uvx projectmind-mcpThe 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-mcpOther 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.pyAvailable Tools (45+)
Category | Tools |
Session |
|
Memory |
|
Search |
|
Context brief |
|
Annotations |
|
Symbols |
|
Exploration |
|
Dependencies |
|
Indexing |
|
Git |
|
Quality |
|
Maintenance |
|
Project |
|
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 |
|
| Embedding model |
|
| Characters per chunk |
|
| Skip files larger than this |
|
| Memory limit for indexing batch |
|
| Max files scanned when building the import graph |
|
| 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/projectset_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.jsProject 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-indexingContributing
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 toolsanalyze_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
Scored across 56 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Your own memory for every AI: Claude, ChatGPT, Cursor, Zed and more. Brings in 20+ sources.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to query a local knowledge base for persistent, searchable project context, reducing re-explanation and token usage.8Functional Source , Version 1.1, ALv2 Future- AlicenseBqualityDmaintenanceGives AI coding assistants cross-session persistent memory with semantic search and task management, fully local.8Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides persistent long-term memory (semantic RAG) for AI coding assistants, enabling them to store and semantically search code and documentation across chat sessions without token limits.5MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent, local-first memory across sessions and projects, with semantic search, global guidelines, and optional autonomous task execution.-