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.

---

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.

---

<p align="center"> <b>Star ⭐ this repo if LocalMind saves you a context switch.</b><br/> Built for agents. Useful for humans. </p>