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.

| What you get | How it works | |---|---| | Safe file access | Scoped reads under your configured roots — nothing outside | | Instant lexical search | ripgrep-backed symbol and pattern search (JS fallback if missing) | | Semantic search | Local vector embeddings via all-MiniLM-L6-v2 — no GPU needed | | Hybrid retrieval | Lexical + semantic fused with RRF ranking for best-of-both results | | Project awareness | Auto-detects projects from marker files, scopes every tool call | | Agent memory | Durable, queryable knowledge graph — your AI remembers what it learned |

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

| Tool | What it does | |------|-------------| | localnest_list_roots | List configured roots | | localnest_list_projects | List projects under a root | | localnest_project_tree | File/folder tree for a project | | localnest_summarize_project | Language and extension breakdown | | localnest_read_file | Read a bounded line window from a file |

Search & Index

| Tool | What it does | |------|-------------| | localnest_search_files | File/path name search — start here for module discovery | | localnest_search_code | Lexical search — exact symbols, regex, identifiers | | localnest_search_hybrid | Hybrid search — lexical + semantic, RRF-ranked | | localnest_get_symbol | Find definition/export locations for a symbol | | localnest_find_usages | Find import and call-site usages for a symbol | | localnest_index_project | Build or refresh the semantic index | | localnest_index_status | Index metadata — exists, stale, backend | | localnest_embed_status | Embedding backend and vector-search readiness |

Memory

| Tool | What it does | |------|-------------| | localnest_task_context | One-call runtime + memory context for a task | | localnest_memory_recall | Recall relevant memories for a query | | localnest_capture_outcome | Capture a task outcome into memory | | localnest_memory_capture_event | Background event ingest with auto-promotion | | localnest_memory_store | Store a memory manually | | localnest_memory_update | Update a memory and append a revision | | localnest_memory_delete | Delete a memory | | localnest_memory_get | Fetch one memory with revision history | | localnest_memory_list | List stored memories | | localnest_memory_events | Inspect recent memory events | | localnest_memory_add_relation | Link two memories with a named relation | | localnest_memory_remove_relation | Remove a relation | | localnest_memory_related | Traverse the knowledge graph one hop | | localnest_memory_suggest_relations | Auto-suggest related memories by similarity | | localnest_memory_status | Memory consent, backend, and database status |

Server & Updates

| Tool | What it does | |------|-------------| | localnest_server_status | Runtime config, roots, ripgrep, index backend | | localnest_health | Compact health summary with background monitor report | | localnest_usage_guide | Best-practice guidance for agents | | localnest_update_status | Check npm for latest version (cached) | | localnest_update_self | Update globally and sync bundled skill (approval required) |

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

| Backend | When to use | |---------|-------------| | sqlite-vec | Recommended. Persistent SQLite, fast and efficient for large repos. Requires Node 22+. | | json | Compatibility fallback. Auto-selected if sqlite-vec is unavailable. |

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:

| Variable | Default | Description | |----------|---------|-------------| | LOCALNEST_INDEX_BACKEND | sqlite-vec | sqlite-vec or json | | LOCALNEST_DB_PATH | ~/.localnest/data/localnest.db | SQLite database path | | LOCALNEST_VECTOR_CHUNK_LINES | 60 | Lines per index chunk | | LOCALNEST_VECTOR_CHUNK_OVERLAP | 15 | Overlap between chunks | | LOCALNEST_VECTOR_MAX_FILES | 20000 | Max files per index run | | LOCALNEST_EMBED_MODEL | sentence-transformers/all-MiniLM-L6-v2 | Embedding model | | LOCALNEST_EMBED_CACHE_DIR | ~/.localnest/cache | Model cache path | | LOCALNEST_RERANKER_MODEL | cross-encoder/ms-marco-MiniLM-L-6-v2 | Cross-encoder reranker model | | LOCALNEST_MEMORY_ENABLED | false | Enable local memory subsystem | | LOCALNEST_MEMORY_DB_PATH | ~/.localnest/data/localnest.memory.db | Memory database path | | LOCALNEST_MEMORY_AUTO_CAPTURE | false | Auto-promote background events | | LOCALNEST_UPDATE_CHECK_INTERVAL_MINUTES | 120 | npm update check interval |

| Variable | Default | Description | |----------|---------|-------------| | LOCALNEST_INDEX_PATH | ~/.localnest/data/localnest.index.json | JSON index path | | LOCALNEST_SQLITE_VEC_EXTENSION | auto-detected | Native vec0 extension path | | LOCALNEST_VECTOR_MAX_TERMS | 80 | Max terms per chunk | | LOCALNEST_EMBED_PROVIDER | huggingface | Embedding backend | | LOCALNEST_EMBED_DIMS | 384 | Embedding vector dimensions | | LOCALNEST_RERANKER_PROVIDER | huggingface | Reranker backend | | LOCALNEST_RERANKER_CACHE_DIR | ~/.localnest/cache | Reranker cache path | | LOCALNEST_MEMORY_BACKEND | auto | auto, node-sqlite, or sqlite3 | | LOCALNEST_MEMORY_CONSENT_DONE | false | Suppress consent prompt | | LOCALNEST_UPDATE_PACKAGE | localnest-mcp | npm package name to check | | LOCALNEST_UPDATE_FAILURE_BACKOFF_MINUTES | 15 | Retry on failed npm check |

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.