# 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](https://img.shields.io/npm/v/@ixxrllg/localmind.svg)](https://www.npmjs.com/package/@ixxrllg/localmind)
[![Node.js](https://img.shields.io/badge/node-%3E%3D22.5-brightgreen)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-ready-purple)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/ixxrllg/localmind?style=social)](https://github.com/ixxrllg/localmind)
[![GitHub issues](https://img.shields.io/github/issues/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>