mindretriever

Knowledge graph and context-pack tooling for AI-assisted software development.

What It Solves

Large codebases make LLM workflows noisy and expensive. Sending entire files to an assistant increases token usage, response time, and irrelevant context.

mindretriever solves this by:

• Building a local knowledge graph of your repo
• Selecting only task-relevant snippets for each question
• Returning a token-optimized context pack for bug fix, feature, refactor, test, review, and optimization workflows
• Tracking measurable token and cost savings over time

Key Features

• Local-first architecture (no external indexing service required)
• Multi-language extraction across backend and frontend assets
• FastAPI service for automation and tool integration
• MCP server for native use in VS Code Copilot Chat and Cursor
• Incremental runs via file-hash cache
• Local SQLite history of runs, graph entities, and savings metrics

Install

Basic install:

pip install mindretriever

Install with MCP support (recommended for VS Code/Cursor chat integration):

pip install "mindretriever[mcp]"

Verify CLI:

mindretriever --help

If command resolution fails on Windows:

python -m mindretriever --help

Quick Start (CLI + API)

1) Analyze a repo

mindretriever run .

Windows-safe fallback:

python -m mindretriever run .

2) Start API

mindretriever-api

Windows-safe fallback:

python -m uvicorn mindretriever.api:app --host 0.0.0.0 --port 8000

Health check:

curl http://localhost:8000/health

3) Create a context pack for a question

curl -X POST http://localhost:8000/api/context-pack \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": 1,
    "task_type": "bug_fix",
    "query": "Why is checkout timing out after deployment?",
    "token_budget": 6000,
    "include_artifacts": true
  }'

4) Check savings proof

curl http://localhost:8000/api/savings

This returns:

• Per-query before/after token counts
• Estimated before/after input cost
• Aggregate total savings across all recorded queries

Use Directly In VS Code And Cursor (MCP)

mindretriever includes an MCP server so chat assistants can call tools automatically while you ask normal questions.

VS Code setup

Create .vscode/mcp.json:

{
  "servers": {
    "mindretriever": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "graphmind.mcp_server"],
      "cwd": "${workspaceFolder}",
      "env": {}
    }
  }
}

Cursor setup

Create .cursor/mcp.json:

{
  "mcpServers": {
    "mindretriever": {
      "command": "python",
      "args": ["-m", "graphmind.mcp_server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Then restart the editor and ask questions normally.

MCP Tools

• mindretriever_analyze(path=".")
  • Builds graph and stores a run record
• mindretriever_context(query, task_type="auto", run_id=None, token_budget=8000)
  • Returns task-focused context pack
• mindretriever_runs(limit=5)
  • Lists recent analysis runs
• mindretriever_savings(limit=20)
  • Shows token and cost savings evidence from local history

API Overview

Method	Endpoint	Purpose
GET	/health	Service health
POST	/api/run	Run extraction + graph build
POST	/api/upload	Upload .md, .docx, .sql files
GET	/api/runs	List run history
GET	/api/runs/{run_id}/graph	Retrieve graph payload for a run
POST	/api/context-pack	Get token-aware context pack
GET	/api/savings	Show local token/cost savings history

Upload field names:

• Preferred: files
• Compatibility alias: file

Example upload:

curl -F "files=@architecture.md" -F "files=@schema.sql" http://localhost:8000/api/upload

Supported Inputs

Detection and extraction support

Extension group	Coverage
.py	Python AST extraction
.sql	SQL schema extraction
.js, .jsx, .ts, .tsx	TypeScript/JavaScript semantic extraction
.vue, .svelte	Section-aware Vue/Svelte semantic extraction
.css, .scss	CSS selector extraction
.md, .txt, .rst	Heading/concept extraction
.docx	Semantic extraction
.go, .java	Detected; deeper extraction planned

Vue/Svelte semantic coverage

• Script/template section-aware parsing
• Imports and component references
• Props (defineProps, export let)
• Emits (defineEmits)
• Stores ($store references)
• Slot usage (<slot ...>)

CLI

mindretriever run [path] [--full]

• Default path: current directory
• Default mode: incremental
• --full: force full reprocessing

Legacy aliases kept for compatibility:

graphmind run .
graphmind-api

Output Artifacts

Generated in graphmind-out/:

• graph.json: portable graph data
• graph.html: human-readable graph visualization
• GRAPH_REPORT.md: summary metrics
• graphmind.db: SQLite database (runs, nodes, edges, savings)
• cache/file_hashes.json: incremental cache
• uploads/: uploaded source documents
• artifacts/: cached context artifacts

Token Savings Methodology

mindretriever records savings on each context request.

Definitions:

• full_tokens: tokens if all candidate project files were sent to the LLM
• pack_tokens: tokens in the generated context pack
• saved_tokens = full_tokens - pack_tokens
• savings_pct = saved_tokens / full_tokens * 100

Cost estimates:

• Uses input-token pricing table (default model: gpt-4o)
• Stored with each record and aggregated in /api/savings and mindretriever_savings

Token counting:

• Uses tiktoken when installed
• Falls back to len(text) // 4 approximation otherwise

Development

git clone https://github.com/RameshJajula/mindretriever.git
cd ramesh-graphmind
pip install -e ".[dev,mcp]"
python -m pytest tests -q

Build and validate package:

python -m build
python -m twine check dist/*

See PUBLISH.md for release steps.

Project Structure

mindretriever/
  __init__.py
  __main__.py
  cli.py
  api.py
graphmind/
  api.py
  cli.py
  mcp_server.py
  token_counter.py
  pipeline.py
  detect.py
  db.py
  context_budget.py
  retrieval_planner.py
  prompt_templates.py
  extractors/
    python_ast.py
    sql_schema.py
    typescript_semantic.py
    vue_svelte_semantic.py
    text_semantic.py
    docx_semantic.py
  graph/
    builder.py
    analytics.py
  exporters/
    json_exporter.py
    html_exporter.py

Compatibility Notes

• Python 3.10+
• SQLite is bundled with Python; no external DB required
• For Windows command resolution issues, use module invocation commands
• Legacy CLI aliases graphmind and graphmind-api remain available

License

MIT. See LICENSE.

Links

• PyPI: https://pypi.org/project/mindretriever/
• Repository: https://github.com/RameshJajula/mindretriever
• Issues: https://github.com/RameshJajula/mindretriever/issues