LocalMind

Give every AI agent perfect memory of your codebase — offline.

LocalMind is a local-first knowledge & context engine for developers and AI coding agents. It indexes your repository into a searchable knowledge base (BM25 + optional embeddings), builds a lightweight import graph, answers questions with citations, and exposes everything through a CLI and an MCP server.

npm Node.js License: MIT MCP GitHub stars GitHub issues

Why LocalMind?

Pain	LocalMind
AI agents forget project context	Persistent local index + MCP tools
Cloud RAG leaks private code	100% local by default (SQLite)
Grep is not enough for questions	BM25 ranking + extractive / generative answers
“What depends on this file?”	Import / link knowledge graph

Works without API keys. Optional OpenAI or Ollama for embeddings and generative answers.

Quick start

Requirements: Node.js ≥ 22.5

Install from npm

npm install -g @ixxrllg/localmind

# in any project
localmind init
localmind index
localmind ask "Where is authentication handled?"
localmind search "jwt middleware"
localmind status

Or without global install:

npx @ixxrllg/localmind init
npx @ixxrllg/localmind index
npx @ixxrllg/localmind ask "Where is authentication handled?"

From source

git clone https://github.com/ixxrllg/localmind.git
cd localmind
npm install
npm run build
node dist/bin/localmind.js init --root /path/to/your/project

CLI

Command	Description
`localmind init`	Create `.localmind/config.json` + SQLite DB
`localmind index`	Walk repo, chunk files, build inverted index (+ optional embeddings)
`localmind index --full`	Force full re-index
`localmind search <query>`	Ranked code/doc search
`localmind ask <question>`	Q&A with citations
`localmind related <path>`	Files linked via imports / markdown links
`localmind status`	Index statistics
`localmind mcp`	Start MCP server on stdio
`localmind config`	Show / update config

Global options:

-r, --root <path>   Project root (default: cwd)
-q, --quiet
--verbose

Examples

localmind init --provider ollama
localmind index
localmind search "chunkText overlap" --mode bm25
localmind ask "How are files ignored during indexing?" --extractive
localmind related src/indexer/indexer.ts
localmind status --json

MCP (Cursor / Claude Code / agents)

localmind mcp --root /path/to/your/project

Example MCP config (Cursor / Claude Desktop):

{
  "mcpServers": {
    "localmind": {
      "command": "node",
      "args": [
        "/absolute/path/to/localmind/dist/bin/localmind.js",
        "mcp",
        "--root",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

Replace paths with your clone of ixxrllg/localmind and the project you want indexed.

Tools

Tool	Purpose
`search_code`	Semantic/lexical search over the index
`ask_codebase`	Question answering with citations
`find_related_files`	Graph neighborhood for a path
`explain_file`	Dump indexed chunks for a file / line range
`index_status`	Stats
`reindex`	Incremental or full re-index

How it works

your repo
   │
   ▼
 walker + ignore rules (.gitignore, defaults)
   │
   ▼
 line-aware chunker ──► SQLite
   │                      ├─ files / chunks
   │                      ├─ BM25 inverted index (terms + postings)
   │                      ├─ import/link edges
   │                      └─ optional embeddings
   ▼
 search (BM25 / vector / hybrid) ──► ask (extractive or LLM)
   │
   ▼
 CLI  ·  MCP  ·  library API

Storage: .localmind/localmind.db (Node built-in node:sqlite)
Default search: BM25 (no network, no models)
Optional: OpenAI / Ollama embeddings + chat

Configuration

.localmind/config.json (created by init):

{
  "version": 1,
  "provider": "none",
  "include": [],
  "exclude": [],
  "maxFileBytes": 524288,
  "chunkSize": 1200,
  "chunkOverlap": 150,
  "incremental": true
}

Environment (optional)

See .env.example:

Variable	Role
`OPENAI_API_KEY`	Embeddings + generative answers
`OPENAI_BASE_URL`	Compatible gateways
`OPENAI_MODEL`	Chat model (default `gpt-4o-mini`)
`OPENAI_EMBEDDING_MODEL`	Default `text-embedding-3-small`
`OLLAMA_BASE_URL`	Default `http://127.0.0.1:11434`
`OLLAMA_MODEL` / `OLLAMA_EMBEDDING_MODEL`	Local models

localmind config --provider openai
# or
localmind config --provider ollama

Library API

import {
  initConfig,
  loadConfig,
  runIndex,
  openDb,
  closeDb,
  search,
  ask,
} from "@ixxrllg/localmind";

const { config } = initConfig({ root: process.cwd() });
await runIndex(config, { full: true });

const db = openDb(config.root);
const hits = await search(db, "authentication middleware");
const answer = await ask(db, config, "How does auth work?");
closeDb(db);

Development

npm install
npm run build
npm test
npm run dev -- init
npm run dev -- index
npm run dev -- ask "What is LocalMind?"

Requirements:

Node.js ≥ 22.5 (uses built-in node:sqlite)

Project layout

src/
  bin/localmind.ts     CLI entry
  cli/                 Commander program + formatting
  core/                config, paths, SQLite
  indexer/             walk, chunk, relations, index pipeline
  search/              tokenize, BM25, embeddings, hybrid
  ask/                 extractive + generative Q&A
  graph/               related files
  mcp/                 MCP server + tools
  index.ts             public exports
tests/                 unit + integration

Roadmap

File watcher / live re-index
Tree-sitter aware chunking
sqlite-vec acceleration
Web UI for exploration
Multi-repo workspaces

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

License

MIT — see LICENSE.

Author

Maintained by @ixxrllg.

localmind