Content
# 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**.
[](https://www.npmjs.com/package/@ixxrllg/localmind)
[](https://nodejs.org/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](https://github.com/ixxrllg/localmind)
[](https://github.com/ixxrllg/localmind/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
```bash
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:
```bash
npx @ixxrllg/localmind init
npx @ixxrllg/localmind index
npx @ixxrllg/localmind ask "Where is authentication handled?"
```
### From source
```bash
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
```bash
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)
```bash
localmind mcp --root /path/to/your/project
```
Example MCP config (Cursor / Claude Desktop):
```json
{
"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](https://github.com/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`):
```json
{
"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 |
```bash
localmind config --provider openai
# or
localmind config --provider ollama
```
---
## Library API
```ts
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
```bash
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](CONTRIBUTING.md). Issues and PRs welcome.
## License
MIT — see [LICENSE](LICENSE).
## Author
Maintained by [@ixxrllg](https://github.com/ixxrllg).
---
<p align="center">
<b>Star ⭐ this repo if LocalMind saves you a context switch.</b><br/>
Built for agents. Useful for humans.
</p>
