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, how the knowledge graph and traversal work, 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 + KG + index

Index data, optional memory, and knowledge graph 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

Run schema migrations

Per-version transaction wrapping upgrades SQLite schemas from v5 through v9 (KG entities, triples, agent diary, conversation sources) with rollback safety.

3

Build services

Workspace, retrieval, indexing, memory, knowledge graph, taxonomy, scopes, dedup, ingest, and hooks services are constructed from the resolved config.

4

Register tools

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

5

Start monitors

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

6

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

Knowledge Graph

Temporal entity-triple store with point-in-time queries and contradiction detection.

• localnest_kg_add_entity
• localnest_kg_add_triple
• localnest_kg_query
• localnest_kg_invalidate
• localnest_kg_as_of
• localnest_kg_timeline
• localnest_kg_stats

Nest/Branch + Traversal

Two-level memory taxonomy and multi-hop graph walking.

• localnest_nest_list
• localnest_nest_branches
• localnest_nest_tree
• localnest_graph_traverse
• localnest_graph_bridges

Agent Diary

Per-agent private scratchpad with scoped isolation.

• localnest_diary_write
• localnest_diary_read

Ingestion + Dedup + Hooks

Conversation import, duplicate detection, and operation callbacks.

• localnest_ingest_markdown
• localnest_ingest_json
• localnest_memory_check_duplicate
• localnest_hooks_stats
• localnest_hooks_list_events

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.

Knowledge graph pipeline

The temporal knowledge graph stores structured facts as subject-predicate-object triples with time validity.

Temporal validity

Every triple carries valid_from and valid_to timestamps. Point-in-time queries via kg_as_of return what was true at any given date.

Multi-hop traversal

Recursive CTEs walk relationships 1-5 hops deep with cycle prevention. graph_bridges discovers cross-nest connections.

Contradiction detection

At write time, new triples are checked against existing valid triples on the same subject+predicate. Conflicts are flagged as warnings without blocking the write.

Entity auto-creation

Entities are auto-created on first triple reference with normalized slug IDs. Provenance is tracked via source_memory_id.

Memory pipeline

Events are scored before they are promoted into durable memory.

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

Nest/Branch hierarchy

Two-level taxonomy: nests are top-level domains, branches are topics within nests. Metadata-filtered recall narrows candidates before scoring.

Semantic dedup

Every write passes through an embedding similarity gate (default 0.92 cosine threshold). Near-duplicates are caught before storage.

Agent isolation

Each agent gets its own memory scope and private diary via the agent_id column (schema v8). Recall returns own + global memories, never another agent's private data.

Conversation ingestion

Markdown/JSON chat exports are parsed into per-turn memory entries with automatic entity extraction and KG triple creation. Re-ingestion is prevented by content hash.

Hooks system

Hook types

Pre-hooks can cancel or transform payloads. Post-hooks run after completion. Wildcards (before:*, after:*) catch all events.

Introspection

localnest_hooks_stats reports registered hook counts. localnest_hooks_list_events shows available hook event names.

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

All source files are TypeScript (96 .ts files, 0 .js). Runtime uses tsx; production builds use tsc.

src/
├── app/                          # Application bootstrap
│   ├── index.ts
│   ├── create-services.ts
│   ├── mcp-server.ts
│   └── register-tools.ts
├── types/
│   └── tree-sitter.d.ts          # Shared type declarations
├── mcp/
│   └── tools/
│       ├── graph-tools.ts        # MCP registration for KG, traversal, diary, ingest, hooks
│       ├── core.ts               # Core MCP tool handlers
│       ├── retrieval.ts          # Retrieval tool handlers
│       ├── memory-store.ts       # Memory store tool handlers
│       └── memory-workflow.ts    # Memory workflow tool handlers
├── services/
│   ├── memory/
│   │   ├── kg.ts                 # Knowledge graph entity and triple CRUD
│   │   ├── graph.ts              # Recursive CTE traversal and bridge discovery
│   │   ├── taxonomy.ts           # Nest/branch hierarchy helpers
│   │   ├── scopes.ts             # Agent diary CRUD and scope isolation
│   │   ├── dedup.ts              # Embedding similarity gate
│   │   ├── ingest.ts             # Conversation parsing and ingestion pipeline
│   │   ├── hooks.ts              # Pre/post operation hook system
│   │   ├── schema.ts             # SQLite schema and migrations
│   │   ├── recall.ts             # Memory recall with embedding search
│   │   ├── store.ts              # Memory storage logic
│   │   ├── relations.ts          # Memory relation management
│   │   └── types.ts              # Memory type definitions
│   ├── retrieval/                # Retrieval pipeline (chunker, embedding, search, reranker, vector-index, sqlite-vec)
│   ├── update/                   # Self-update service
│   └── workspace/                # Workspace and project detection
├── cli/
│   ├── ansi.ts                   # ANSI color and formatting utilities (shared)
│   ├── output.ts                 # Structured output helpers (shared)
│   ├── spinner.ts                # ora spinner wrapper (shared)
│   ├── options.ts                # Global CLI flag parser
│   ├── help.ts                   # Colored help renderer
│   ├── router.ts                 # Noun-verb subcommand dispatcher
│   ├── parse-flags.ts            # Flag parsing utilities
│   ├── tool-count.ts             # MCP tool count helper
│   └── commands/
│       ├── memory.ts             # Memory CLI (add, search, list, show, delete)
│       ├── kg.ts                 # Knowledge Graph CLI (add, query, timeline, stats)
│       ├── skill.ts              # Skill management CLI (install, list, remove)
│       ├── mcp.ts                # MCP lifecycle CLI (start, status, config)
│       ├── ingest.ts             # Conversation ingestion CLI
│       ├── completion.ts         # Shell completion generators (bash, zsh, fish)
│       ├── dashboard.ts          # Interactive terminal dashboard
│       ├── onboard.ts            # Guided first-run setup wizard
│       ├── selftest.ts           # End-to-end pipeline validation
│       └── hooks.ts              # Hook management CLI
├── runtime/                      # Config, home layout, sqlite-vec extension, version, warning filter
├── migrations/                   # Config migration scripts
└── setup/                        # Client installer for AI tools

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, memory, and knowledge graph stay on the local machine.

Thin handlers

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

SQLite for everything

Index, memory, knowledge graph, and agent diary all use SQLite. Zero external database dependencies.

Additive migrations

Schema versions v5 through v9 are all additive and backward-compatible. Per-version transaction wrapping ensures safe rollback on failure.