LocalNest MCP

[MANDATORY_START] The single most important tool for task initialization. Rehydrates project context, recalled memories, KG entities, relevant files, recent changes, and suggested actions in one call. Always call this BEFORE deeper research.

Run a comprehensive self-audit of LocalNest health. Returns memory coverage by project, KG density metrics (entities, triples, orphans, duplicates, connected components), unpopulated nests, broken bridges, stale memories, a 0-100 health score, and actionable suggestions. Call once to get a full integrity dashboard.

Create a point-in-time backup of the LocalNest memory database using SQLite VACUUM INTO. The backup is a clean, compacted SQLite file verified with PRAGMA integrity_check. If destination is omitted, the backup is written to {memoryDbDir}/backups/{timestamp}.db.

[COMPLETE_MISSION] One-call mission summary capture. Use this after completing a task, fixing a bug, or making a major architectural decision to persist the "Winner" state for future agents.

Read recent diary entries for a specific agent. Only returns entries belonging to the requesting agent.

Write a private diary entry for an agent. Diary entries are isolated and only visible to the owning agent.

Return active embedding backend/model status and vector-search readiness.

Report that a file was edited and receive proactive hints about high-importance memories linked to it. Memories with importance >= 70 that reference the file are flagged with suggest_update=true, indicating the memory may need updating to reflect the file change.

Search across memory entries, code chunks, and knowledge graph triples in a single call. Results are re-ranked across all sources using normalized scores. Each item includes a source field ("memory", "code", or "triple"). Use the sources parameter to limit which backends are queried.

Find every call site of a function or method across indexed files. Returns file path, line number, and surrounding context for each call. Requires the project to be indexed first via localnest_index_project.

Jump to the declaration location(s) of a symbol across TypeScript, JavaScript, Python, Go, and Rust files. Returns file path, line range, and declaration text. Requires the project to be indexed first via localnest_index_project.

Find every class, struct, or object that implements a given interface or trait. Supports TypeScript implements, Python class inheritance, Rust impl-for, and Go struct patterns. Requires the project to be indexed first via localnest_index_project.

[USAGE_ANALYSIS] Find call sites and import usages of a symbol by name.

[SYMBOL_INDEX] Look up symbol definitions/exports by name using fast regex search.

Discover cross-nest bridges (default) or cross-branch bridges within a nest. Use mode="cross-branch" with a nest to find entities that span different branches within that nest.

Traverse the knowledge graph from a starting entity with configurable max hops (default 2). Uses recursive CTEs with cycle prevention. Returns discovered entities with path information.

Return a compact runtime health summary for fast smoke checks.

Get task-scoped tool guidance. Describe what you want to do and receive a tailored list of tools, workflow steps, and tips.

Returns all valid hook event names that listeners can subscribe to. Covers memory lifecycle (store, update, delete, recall), knowledge graph operations (addEntity, addTriple, invalidate), graph traversal, diary, ingestion, dedup, taxonomy, and catch-all wildcards.

Returns hook system statistics: whether hooks are enabled, total registered listener count, and a breakdown of listener counts per event type.

Build or refresh semantic index for a project or across all roots.

Return local semantic index status and metadata.

Ingest a JSON conversation export (array of {role, content, timestamp?} objects) into memory entries and knowledge graph triples. Pass the full JSON text directly.

Ingest a Markdown conversation export into memory entries and knowledge graph triples. Pass the full text content directly — file reading is handled by the CLI, not MCP tools.

Create up to 500 entities in a single transactional batch. Returns created/duplicate counts and per-row errors. Use response_format "verbose" to get back an ids[] array.

Create or update an entity in the knowledge graph. Entity IDs are auto-generated as normalized slugs (lowercase, underscored).

Add a subject-predicate-object triple to the knowledge graph. Entities are auto-created on first reference. Detects contradictions (same subject+predicate with different valid object) and warns without blocking.

Add up to 500 triples in a single transactional batch. Entities auto-created on first reference. Deduplicates against active triples.

Query triples for an entity at a specific point in time. mode="event" (default) returns facts whose valid_from/valid_to bracket the date (event-time axis). mode="transaction" returns every triple LocalNest knew at that time via recorded_at, regardless of valid_to (transaction-time axis).

Retroactively scan existing memories and create KG triples linking them to matching entities. Processes memories in batches. Use limit/offset for pagination.

Delete up to 100 knowledge graph entities in one call. Cascades: also deletes all triples where each entity is subject or object. Returns count of deleted entities and removed triples.

Delete a knowledge graph entity by ID. Cascades: also deletes all triples where the entity is subject or object.

Hard-delete up to 100 knowledge graph triples by ID. Unlike invalidate (which sets valid_to), this permanently removes the triples.

Set valid_to on a triple to mark it as no longer current. The triple remains in history but is excluded from current-state queries.

Query all relationships for an entity in the knowledge graph with optional direction filtering (outgoing, incoming, or both).

Get knowledge graph statistics: total entity count, total triple count, active triple count, and breakdown by predicate type.

Get a chronological timeline of all triples for an entity, including invalidated facts. Ordered by valid_from date ascending.

List first-level project directories under a root.

List configured local roots available to this MCP server.

Link two memory entries with a named relation. Use to build a traversable knowledge graph (e.g. "depends_on", "contradicts", "supersedes", "related").

Ingest a background work event and auto-promote meaningful events into durable memory.

Check whether content is a semantic duplicate of an existing memory entry. Uses embedding cosine similarity with configurable threshold (default 0.92). Returns the matching entry when a duplicate is found.

Delete a stored memory entry and all of its revisions.

Delete up to 100 memory entries in a single call. Returns the count of deleted entries and per-row errors for IDs that were not found or failed.

List recently captured memory events and whether they were promoted into durable memory.

Fetch one stored memory with revision history.

List stored memories with optional scope, kind, nest, branch, and tag filters. Use item_format=compact to drop content/metadata (~50% fewer tokens) or lite to return only id+title (~85% fewer tokens).

Recall the most relevant local memories for a task or query. Use item_format=compact to drop content/metadata (~50% fewer tokens) or lite to return only id+title (~85% fewer tokens).

Return all memory entries linked to a given memory ID, traversing the knowledge graph one hop in both directions.

Remove a relation between two memory entries.

Return local memory feature status, consent state, and backend compatibility.

Store a durable local memory entry.

Store up to 100 memory entries in a single atomic transaction. Deduplicates via fingerprint and optional semantic similarity. Returns created/duplicate counts and per-row validation errors.

Find semantically similar memory entries that could be linked to a given memory. Uses dense embeddings (all-MiniLM-L6-v2) when available, falls back to token overlap. Returns candidates ranked by similarity without creating any relations — use localnest_memory_add_relation to confirm.

Update a stored memory entry and append a revision.

List all branches (topics) within a specific nest with their memory entry counts.

List all nests (top-level memory domains) with their memory entry counts.

Get the full taxonomy tree: all nests, their branches, and memory counts at each level.

Scan a directory for projects and create seed memory entries for those with zero existing memories. Detects package.json, Cargo.toml, go.mod, pyproject.toml, pom.xml, build.gradle, and .git. Use dry_run=true to preview without writing.

Return a compact tree of files/directories for a project path.

Read a bounded chunk of a file with line numbers.

Preview every location that would change when renaming a symbol. Does NOT modify any files -- returns a dry-run list of changes grouped by file. Requires the project to be indexed first via localnest_index_project.

Restore the LocalNest memory database from a backup file. Verifies backup integrity before replacing the live database. IMPORTANT: The MCP server must be restarted after restore for changes to take effect.

[EXACT_MATCH] Search text across files under a project/root and return matching lines. Best for exact symbol names, imports, or known identifiers.

[FAST_DISCOVERY] Search file paths and names matching a query. Use this first when looking for a module, feature, or component by name (e.g. "sso", "payment", "auth").

[DEEP_ANALYSIS] Run lexical + semantic retrieval and return RRF-ranked results. Best for queries where concepts and context matter as much as exact keywords.

Return runtime status and active configuration summary for this MCP server.

Return a high-level summary of a project directory.

[QUICK_REHYDRATION] Bundle runtime status, memory state, and relevant recall for a non-trivial task in one call.

Teach the agent a durable behavior rule. Stores a high-importance feedback memory that auto-surfaces in agent_prime when future tasks match the instruction domain. Use this to set persistent preferences, coding standards, or workflow rules that should apply across sessions. Teach memories can be listed (kind=feedback), updated, or deleted via existing memory CRUD tools.

Update localnest-mcp globally via npm and sync bundled skill. Supports stable, beta, or explicit version targets. Requires explicit user approval.

Check npm for the latest localnest-mcp version on the selected channel (cached, default every 120 minutes).

Return concise best-practice guidance for users and AI agents using this MCP.

Cross-session delta: new memories, KG triples, file changes, and commits since a given timestamp or last session.