LocalNest MCP

Your codebase. Your AI. Your machine — no cloud, no leaks, no surprises.

LocalNest is a local-first MCP server that gives AI agents safe, scoped access to your code — with hybrid search, semantic indexing, and persistent memory that never leaves your machine.

📖 Full documentation · Architecture deep dive

Why LocalNest?

Most AI code tools phone home. LocalNest doesn't.

Everything — file reads, vector embeddings, memory — runs in-process on your machine. No cloud subscription, no rate limits, no data leaving your box. And because it speaks MCP, any compatible client (Cursor, Windsurf, Codex, Kiro, Gemini CLI) can plug in with one config block.

Quick Start

npm install -g localnest-mcp
localnest setup
localnest doctor

3. Drop this into your MCP client config

Setup auto-writes the config for detected tools. You'll also find a ready-to-paste block at ~/.localnest/config/mcp.localnest.json:

{
  "mcpServers": {
    "localnest": {
      "command": "localnest-mcp",
      "startup_timeout_sec": 30,
      "env": {
        "MCP_MODE": "stdio",
        "LOCALNEST_CONFIG": "~/.localnest/config/localnest.config.json",
        "LOCALNEST_INDEX_BACKEND": "sqlite-vec",
        "LOCALNEST_DB_PATH": "~/.localnest/data/localnest.db",
        "LOCALNEST_INDEX_PATH": "~/.localnest/data/localnest.index.json",
        "LOCALNEST_EMBED_PROVIDER": "huggingface",
        "LOCALNEST_EMBED_MODEL": "sentence-transformers/all-MiniLM-L6-v2",
        "LOCALNEST_EMBED_CACHE_DIR": "~/.localnest/cache",
        "LOCALNEST_EMBED_DIMS": "384",
        "LOCALNEST_RERANKER_PROVIDER": "huggingface",
        "LOCALNEST_RERANKER_MODEL": "cross-encoder/ms-marco-MiniLM-L-6-v2",
        "LOCALNEST_RERANKER_CACHE_DIR": "~/.localnest/cache",
        "LOCALNEST_MEMORY_ENABLED": "false",
        "LOCALNEST_MEMORY_BACKEND": "auto",
        "LOCALNEST_MEMORY_DB_PATH": "~/.localnest/data/localnest.memory.db"
      }
    }
  }
}

Windows: Use the config written by localnest setup — it sets the correct command for your platform automatically.

Restart your MCP client. If it times out, set startup_timeout_sec: 30 in your client config.

Requirements: Node.js >=18 · ripgrep recommended but optional

AST-aware chunking ships by default for JavaScript, Python, Go, Bash, Lua, and Dart. Other languages still index cleanly with line-based fallback chunking.

The current stable runtime uses @huggingface/transformers for local embeddings and reranking. New setup defaults use huggingface, and older xenova configs remain accepted as a compatibility alias.

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt-get install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

Upgrade

localnest upgrade              # latest stable
localnest upgrade stable       # latest stable
localnest upgrade beta         # latest beta
localnest upgrade <version>    # pin to a specific version
localnest version              # check current

How Agents Use It

Two workflows cover almost everything:

Fast lookup — find it, read it, done

Best for pinpointing a file, symbol, or code pattern.

localnest_search_files   → find the module by path/name
localnest_search_code    → find the exact symbol or identifier
localnest_read_file      → read the relevant lines

Deep task — debug, refactor, review with context

Best for complex work where memory and semantic understanding matter.

localnest_task_context    → one call: runtime status + recalled memories
localnest_search_hybrid   → concept-level search across your codebase
localnest_read_file       → read the relevant sections
localnest_capture_outcome → persist what you learned for next time

Tool success ≠ useful result. A tool can return OK and still be empty. Treat non-empty file matches and real line content as meaningful evidence — not just process success.

Tools

Workspace & Discovery

Search & Index

Memory

Server & Updates

All tools support response_format: "json" (default) or "markdown". List tools return total_count, has_more, next_offset for pagination.

Memory — Your AI Doesn't Forget

Enable memory during localnest setup and LocalNest starts building a durable knowledge graph in a local SQLite database. Every bug fix, architectural decision, and preference your AI agent touches can be recalled on the next session.

• Requires Node 22.13+ — search and file tools work fine on Node 18/20 without it

• Memory failure never blocks other tools — everything degrades independently

How auto-promotion works: events captured via localnest_memory_capture_event are scored for signal strength. High-signal events — bug fixes, decisions, preferences — get promoted into durable memories. Weak exploratory events are recorded and quietly discarded after 30 days.

Index Backend

Check localnest_server_status → upgrade_recommended to know when to migrate.

Configuration

Setup writes everything to ~/.localnest/:

~/.localnest/
├── config/   → localnest.config.json, mcp.localnest.json
├── data/     → SQLite index + memory databases
├── cache/    → Model weights, update status
├── backups/  → Config migration history
└── vendor/   → Managed native deps (sqlite-vec)

Config priority: PROJECT_ROOTS env → LOCALNEST_CONFIG file → current directory

Key environment variables:

Install Note

0.0.5 promotes the beta.9 install/runtime fixes into the stable line, including bundled skill version reporting, installed-runtime validation hardening, and the simplified skill-sync flow. Some npm environments may still show a single upstream deprecation warning from the ONNX runtime dependency chain; LocalNest functionality is unaffected.

Performance tips:

• Scope queries with project_path + a narrow glob whenever possible

• Start with max_results: 20–40, widen only when needed

• Leave reranking off by default — enable only for final precision passes

Skill Distribution

LocalNest ships a bundled AI agent skill for Claude Code, Cursor, Codex, and other supported clients. Install once and your agent knows exactly how to use every tool.

localnest install skills             # install or update bundled skills
localnest install skills --force     # force reinstall
localnest-mcp-install-skill          # legacy alias

Shell CLI tools for automation and hooks:

localnest-mcp-task-context --task "debug auth" --project-path /path/to/project
localnest-mcp-capture-outcome --task "fix auth" --summary "..." --files-changed 2

Both commands accept JSON on stdin. Install from GitHub:

npx skills add https://github.com/wmt-mobile/localnest --skill localnest-mcp

Auto-Migration

Upgrade without ceremony. On startup, LocalNest automatically migrates older config schemas and the flat ~/.localnest layout into the new config/, data/, cache/, and backups/ structure. No manual reruns, no broken configs after upgrades.

Security

LocalNest follows the OSS security pipeline pattern:

• CI quality gate — quality.yml

• CodeQL static analysis — codeql.yml

• OpenSSF Scorecard — scorecards.yml

• Dependabot — .github/dependabot.yml

• Public scorecard — https://scorecard.dev/viewer/?uri=github.com/wmt-mobile/localnest

Contributing

See CONTRIBUTING.md · CHANGELOG.md · SECURITY.md

New to the codebase? Start with the Architecture Overview — covers how the server boots, how search and memory work, and where everything lives.

Contributors

Thanks to everyone who contributes code, docs, reviews, testing, and issue reports.