Installation

The recommended path is a global install followed by setup and doctor. LocalNest v0.3.0 is a modernization release that introduces a premium CLI with an interactive TUI dashboard. It features 74 MCP tools across temporal knowledge graph, multi-hop traversal, and agent-scoped memory tracks.

Requirements

• Node.js >=18: Required for core search and file tools.
• Node.js >=22: Recommended. Required for the local memory subsystem and TUI dashboard.
• ripgrep (rg): Highly recommended for high-performance lexical search.

Memory Requirement

If you are using the memory subsystem, ensure you are on Node 22.13.1 or higher to support the underlying SQLite-vec extensions.

Recommended Install

Choose your release track:

Stable Track (v0.2.0):

npm install -g localnest-mcp

Beta Track (v0.3.0-beta.2 — Interactive CLI & TUI):

npm install -g localnest-mcp@beta

Quick Start Sequence

# 1. Install the package (Stable or Beta)
npm install -g localnest-mcp

# 2. Install bundled skills to your AI clients
localnest install skills

# 3. Generate configuration & Provision backends
localnest setup

# 4. Verify the environment & Diagnostics
localnest doctor

# 5. Launch the Dashboard (Beta only)
localnest dashboard

Bundled Skill Targets

localnest install skills installs tool-specific skill packages from one canonical LocalNest skill source.

It automatically detects and installs to:

• ~/.cursor/skills
• ~/.codeium/windsurf/skills
• ~/.gemini/antigravity/skills
• ~/.cline/skills
• ~/.continue/skills
• ~/.agents/skills

MCP Client Config

After setup, copy the mcpServers block from ~/.localnest/config/mcp.localnest.json into your client configuration.

{
  "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_MEMORY_ENABLED": "true"
      }
    }
  }
}

Enabling Semantic Search

LocalNest uses @huggingface/transformers for local embedding generation (MiniLM-L6-v2). This is installed automatically during postinstall. If it wasn't installed, add it manually:

cd $(npm root -g)/localnest-mcp
npm install --no-save @huggingface/transformers

Run localnest doctor to verify embedding status.

Installing from GitHub

Known npm Limitation

Direct npm install -g git+https://... may fail with TAR_ENTRY_ERRORS. This is a known npm bug where git dependencies auto-bundle node_modules into the tarball, causing extraction failures for packages with large native binaries (onnxruntime, sharp).

Recommended: clone, pack, then install

git clone https://github.com/wmt-mobile/localnest.git
cd localnest
git checkout release/0.3.0  # or main for stable
npm pack
npm install -g ./localnest-mcp-*.tgz

Alternative: install with --ignore-scripts, then rebuild

npm install -g --ignore-scripts git+https://github.com/wmt-mobile/localnest.git#release/0.3.0
cd $(npm root -g)/localnest-mcp && npm install

After either method, enable semantic search:

cd $(npm root -g)/localnest-mcp && npm install --no-save @huggingface/transformers

Troubleshooting

• Startup Timeout: Keep startup_timeout_sec at 30 or higher.
• Diagnostics: Run localnest doctor --verbose for a full health scan.
• Model Warmup: Setup downloads embedding models to ~/.localnest/cache. Ensure this path is writable.
• Beta Features: If localnest dashboard is not found, ensure you installed @beta.

Common Install Issues

Issue	Cause	Fix
TAR_ENTRY_ERROR ENOENT	npm git-dep auto-bundling bug	Use npm pack + npm install -g ./file.tgz
spawn sh ENOENT	Concurrent extraction race	Same as above
tarball data (null) corrupted	Stale npm cache	npm cache clean --force then retry
Semantic search disabled	@huggingface/transformers not installed	cd $(npm root -g)/localnest-mcp && npm install --no-save @huggingface/transformers
localnest: command not found	Global bin not in PATH	Check npm root -g is accessible
tsx not found	Incomplete install	cd $(npm root -g)/localnest-mcp && npm install

---

Note on v0.3.0: The modernization cycle focuses on premium developer experience. All tool names and API contracts from 0.1.0/0.2.0 are fully preserved.