Architecture

Use this page when you need a systems view of LocalNest instead of task-by-task setup or tool reference guidance. It explains how the MCP server boots, how retrieval is fused, how indexing and memory are structured, and which runtime decisions shape the product.

Transport

stdio MCP server

All interaction happens over JSON-RPC on stdio. There is no HTTP server in the runtime path.

Retrieval

Lexical + semantic

Exact search, semantic retrieval, and optional reranking are combined into one local-first workflow.

State

Local memory + index

Index data and optional memory stay on disk on the user’s machine rather than leaving the environment.

System shape

Boot sequence

1

Load runtime config

Environment variables and localnest.config.json are merged into one runtime config.

2

Build services

Workspace, retrieval, indexing, memory, and update services are constructed from the resolved config.

3

Register tools

MCP handlers are bound to the service layer with schema validation and response normalization.

4

Start monitors

Background staleness and health monitors are initialized without blocking the process exit path.

5

Open stdio transport

The MCP server begins serving requests to the connected AI client.

Tool groups

Core

Status, health, usage guidance, and self-update behavior.

• localnest_server_status
• localnest_health
• localnest_usage_guide
• localnest_update_self

Retrieval

File discovery, exact search, hybrid retrieval, and line-window verification.

• localnest_search_files
• localnest_search_code
• localnest_search_hybrid
• localnest_read_file

Memory Store

Durable project knowledge, memory recall, and relation management.

• localnest_memory_store
• localnest_memory_recall
• localnest_memory_related
• localnest_memory_add_relation

Memory Workflow

Higher-level task context and outcome capture for day-to-day agent work.

• localnest_task_context
• localnest_capture_outcome
• localnest_memory_capture_event

Project detection

Configured roots are scanned for marker files such as package.json, go.mod, or Cargo.toml. Matching directories become named projects, and most tools can then be scoped with project_path.

Retrieval pipeline

Hybrid retrieval runs lexical and semantic signals in parallel, then merges them with reciprocal rank fusion. Reranking is optional and used when callers want higher final precision.

Signal	Purpose	Notes
Lexical	Exact identifiers, imports, errors, regex patterns	Uses ripgrep when available, with JS fallback
Semantic	Concept-level retrieval	Local embeddings, no external search service
Reranker	Final precision pass	Optional, kept off by default in many workflows

Indexing model

Files are split into overlapping chunks before term and embedding data is stored.

Chunking

Default chunk size is 60 lines with 15 lines of overlap.

Fallback behavior

Supported languages use AST-aware chunking; other files fall back to line-based chunking.

Memory pipeline

Events are scored before they are promoted into durable memory.

Memories can also be linked into a graph with named relations.

Request handling

Handlers validate with Zod and delegate the real behavior to services.

Background runtime work

Staleness monitor

Checks whether indexed files changed on disk and refreshes state when configured to do so.

Health monitor

Runs integrity checks, pruning, and database maintenance tasks on a background cadence.

Source layout

src/
├── app/
├── mcp/
├── services/
├── runtime/

Design decisions

stdio only

No HTTP server is exposed in the normal runtime path.

Graceful degradation

Missing optional subsystems should fall back instead of taking retrieval down with them.

Local-first execution

Embeddings, reranking, indexing, and memory stay on the local machine.

Thin handlers

Handlers validate and normalize; service modules own the business logic.