Repository avatar
Search & Data Extraction
v12.2.7
active

nestweaver

io.github.Kehl-io/nestweaver

Local code knowledge graph: search symbols, trace callers, and inspect change impact across repos.

Documentation

NestWeaver

Your codebase as a queryable graph — built for AI agents.

CI MIT License Latest Release Stable Rust for source builds

Website · Docs · npm · Releases

NestWeaver indexes source code and Markdown into a local knowledge graph.
Search symbols, trace callers and dependencies, and get task-focused context
from the CLI or your AI coding tool through MCP.

NestWeaver uses Tree-sitter to parse 32 languages and resolves cross-file references with confidence scores. Its graph helps you explore an unfamiliar repository, assess a change's impact, and give an agent relevant symbols and relationships. Indexing and structural queries run locally; semantic embeddings and shared-server connections are optional.

Quick Start · Install options · CLI reference · MCP server · Agent setup verification · Upgrade guidance


NestWeaver terminal demo

Index a repo and query it in seconds


32 Languages
Tree-sitter parsing for JS, TS, Go, Python, Rust, Java, C/C++, Lua, Scala, Elixir, Zig, Vue, Svelte, and 18 more. Tracks CALLS, IMPORTS, USES, and ACCESSES edges. Resolves monorepo workspaces and tsconfig path aliases. As of 9.0.0 .h files are parsed with the C++ grammar (they used to get C, which has no class keyword) and C++ #include resolves to real IMPORTS edges.

Markdown Brain
Index Obsidian vaults alongside code. Unified knowledge graph across notes and symbols.

Intent-Aware Context
Personalized PageRank with per-edge-type weights (CALLS, IMPORTS, USES, ACCESSES) and --intent tuning surfaces exactly the symbols relevant to your task.

43-Tool MCP Server
Model Context Protocol tools for AI agents. Drop-in for any MCP client, lite mode for Cursor. Daemon architecture enables concurrent access from multiple AI tools without lock contention.

PR Impact & Dead Code
Confidence-weighted blast radius with impact_score decay through edges; co-change mining from git history (Jaccard-scored file pairs); type-aware call resolution via AST-extracted type bindings; dead code detection with type exclusion and manifest-driven entry points; hub/bridge analysis and graph export.

16 AI Tool Integrations
One-command setup for Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot in VS Code, Aider, Kiro, and more. Also offered automatically on the first interactive in-repo index.

Agent Interaction Memory
Opt-in usage tracking that learns from what agents actually use. It re-ranks only the nodes a query's walk already reached, by at most +5%, and never adds a node the seed cannot reach. Privacy-first: local-only, records UIDs and timestamps only, no content capture. Enable with --track-interactions.

Quick Start

1. Install the CLI

Upgrading an existing database? Stop the old daemon and back up with the previous binary first.

With Node.js 18+ on macOS 13.3+ or Linux with glibc 2.35+ (x86_64 or arm64):

npm install --global nestweaver
nestweaver --version

npm installs the matching prebuilt binary as an optional dependency; no Rust compiler or install-time script is needed. Keep optional dependencies enabled. Windows and musl/Alpine do not have published binaries. For a verified GitHub Release archive or a source build, see Install and INSTALL.md.

2. Index and query your repository

Run these commands from your repository root:

nestweaver index --repo . --db "$(pwd)/nestweaver.lbug"
nestweaver search "main" --db ./nestweaver.lbug
# Replace processPayment with a symbol name found in your search results
nestweaver context processPayment --db ./nestweaver.lbug

search finds symbols by name; context returns related symbols and their relationships around a name, UID, or repo-relative file path. The database and its sidecars stay on disk so subsequent queries can reuse the index. A local background daemon owns the database and starts automatically on first use.

Index reports its selected database target on stderr unless --quiet is set; the target is not a field in the --json payload. When querying from another directory, pass the same absolute database path with --db. The first command uses an absolute path for daemon startup. Explicit --db keeps these examples bound to the same graph even if you have other instances configured.

3. Connect your AI coding tool (optional)

From the same repository root:

nestweaver setup --db "$(pwd)/nestweaver.lbug"
# Or choose a specific installed integration:
nestweaver setup claude-code --db "$(pwd)/nestweaver.lbug"

setup detects supported tools and writes their MCP registration and instructions. Use an absolute database path so clients launched from another directory still query the same graph. It supports 16 integrations, including Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot in VS Code. Most config files are written in the repo; Windsurf uses its user-level config, and Cline gets a printed snippet to paste. setup attempts every tool, lists what it wrote for each, and exits non-zero if any tool failed. Restart or reload your client and check its tool list to confirm activation. Cursor gets the six-tool lite set; other MCP integrations use the full set. For a client you configure manually, launch nestweaver mcp --db /absolute/path/to/nestweaver.lbug as its stdio server; see MCP Server for tool filtering and lifecycle details.

The first interactive index run from inside your repo also offers setup. The prompt is skipped in CI, scripts, and non-TTY runs; index --setup explicitly requests setup at the indexed repo root. Use setup --force only when you want to overwrite customized skill/guide files or rebind an existing registration to a different --db (a changed --db is reported otherwise). It never overwrites .github/copilot-instructions.md, or an AGENTS.md without NestWeaver's begin/end markers.

# Keep the graph current as you edit (runs until interrupted)
nestweaver watch . --db ./nestweaver.lbug

Run nestweaver --help for the full command list. Most commands support --json for machine-readable output. Existing users should read the upgrade notes below before using an older database with a new binary.

Upgrading — re-index before you trust a ranking

Upgrading an existing database? Check compatibility before querying it:

Builds with LadybugDB 0.22.3 read the 0.21.2 database format, but a writable open/checkpoint can upgrade its storage format from 47 to 49. Stop the old daemon and back up with the previous binary before upgrading. To downgrade, reinstall that binary and restore the pre-upgrade backup; do not point it at the upgraded file. See the storage upgrade guidance.

Previous release 12.2.6 uses resolver generation 22 and parsed cache 16. LadybugDB 0.22.1 is unchanged from 12.2.5. Anonymous JavaScript/TypeScript default functions now own calls in their bodies; Svelte, Vue and Astro function spans skip destructured/default parameters. Generation 21/cache 15's PHP static-method ownership and inheritance facts and the preceding Dart/PowerShell grammar updates remain included. Force re-index each repository once after upgrading to publish the new parser facts; invalidating the parse cache alone does not replace symbols and edges already stored in the graph.

12.2.7 uses LadybugDB 0.22.3 (the same storage format 49), resolver generation 23 and parsed cache 17. Scala grammar 0.26.9 repairs Scala 2 given/enum identifiers and other grammar boundaries. Force-index each repository once after upgrading from generation 22 as well.

Canonical publication PageRank now consistently covers the unified code and notes graph after indexing, watching and rebuilding. Older canonical sidecars with a code-only scope are disclosed and recomputed lazily on the first ranked query; no graph rebuild is required for this ranking migration alone. Explicit scoped ranking APIs retain their requested scope.

daemon status --json reports both client and daemon resolver generations. An older daemon without this provenance reports null; differing builds with the same product version disclose skew without automatically replacing a writer.

  • A database from before LadybugDB 0.21 needs a publication rebuild, not just a forced index. Back it up and follow the error's recovery command and storage-engine upgrade guide.
  • For a compatible database, run nestweaver stale-check --db <db>. 12.2.7 requires resolver generation 23 (12.2.6 used 22). If your binary reports a generation-stale graph, run nestweaver index --repo <path> --db <db> --force for each repository. A plain incremental index does not repair generation-stale graphs.
  • Generation 16 preserves declaring-package origin through Go factory-call receiver chains and revisits unchanged importers when Go package methods are added or recreated. Existing graphs may retain missing CALLS edges until the forced index above.
  • Generation 17 confines Go initializer and case-clause bindings to their statement or clause, restoring valid calls after those scopes end. Cached parses are invalidated to discard the old lexical lifetimes; existing graphs need the forced repository index above. Resolution-dependency format is unchanged.
  • Generation 18 and parsed cache 12 invalidate Scala parses from before the grammar 0.26.3 update, which recovers declarations such as local case classes and Scala 2 export identifiers. After upgrading to a release containing this change, force re-index each repository using the command above. An unchanged incremental run does not repair an older graph; stale-check continues to report it as outdated until the forced index succeeds.
  • 12.2.4 generation 19 and parsed cache 13 additionally repair PHP function resolution by namespace across directories, including use function aliases and duplicate refusal. Existing graphs need the forced repository index above. PHP changes conservatively re-resolve repository PHP callers because a new declaration can satisfy a previously unresolved call or create ambiguity. Ordinary index/watcher scans reuse valid cached parses; Git/server incremental repair reparses PHP peers. No-change runs remain no-ops.
  • Markdown derivation version 3 repairs percent-encoded Markdown URL paths and proven absolute in-vault note paths. Eligible vaults disclose stale derivation until re-derived; run nestweaver brain refresh <vault> --db <db> after upgrading. This is separate from repository resolver generation; literal wikilinks keep their existing spelling semantics.
  • The current source also infers method receivers from typed Go slice range elements, including qualified types and exact factory returns. Generation 14 requires the same forced repository re-index to add the missing call edges; generation15 additionally handles inferred var slices, parenthesized range sources and single named factory results. Parsed cache10 reparses unchanged declarations for normalized return types and complete var/const/parameter shadow guards.
  • Upgrading to 12.2.7 needs a forced re-index of every repository. Run nestweaver index --repo <path> --force once per repository, using your usual --db and --config bindings. Plain incremental indexing can leave an unchanged graph on its old generation. stale-check exits 2 until repaired.
  • Refresh registered vaults if crossing the earlier Markdown derivation upgrade. Run nestweaver brain refresh <vault> with the same bindings to re-derive note-to-code relationships against the rebuilt graph. If upgrading from before 12.2.2, this also repairs frontmatter wikilinks and block references.
  • New databases do not need migration. Vaults do not carry a code resolver generation; see the detailed notes for separate Markdown derivation changes.
Detailed migration notes and changes for scripts and server clients

12.2.6 uses RESOLVER_GENERATION 22; 12.2.5 used 21. Every graph indexed by a generation different from the running binary must be re-indexed. Compatibility is an EXACT MATCH, not a floor, so a graph written by any other generation — older or newer — is treated as untrustworthy.

9.0.0 took it from 3 to 4, and generations 5 and 6 followed. The 9.0.0 bump changed edge SHAPE; 5 and 6 changed which symbols are persisted as ENTRY POINTS, which is what dead-code walks from. Generation 7 (nw-687) adds missing CALLS/definition edges for CommonJS module.exports.X/exports.X function definitions, which a stale graph is missing entirely. Generation 8 (nw-688) renames JS/TS test-runner blocks so describe('getTier') no longer shadows the real getTier. Generation 9 replaces file-level import proxies with actual binding users, corrects receiver and export resolution, and persists exported executable roots. Upgrading from generation 8 requires a forced re-index of every repository; stale-check exits 2 and dead-code refuses until the graph matches. Generation 10 (nw-113) restricts a block-scoped JS/TS callable to its block, and gives the calls a JS/TS/Python/PHP file makes at its top level a per-file <module> owner (parsed cache 6). The same bump carries these JS/TS parser and resolver fixes:

ChangeEffect on the graph
Generators (function*, async function*, const g = function* …, CommonJS exports.g = function*) are Function symbols (nw-791)Their callers gain edges; their body calls are no longer top-level code
Generators scope their parameters and varsA generator's parameter no longer shadows a same-named module function
A .js bare-parameter arrow (const f = x => …) is a functionIt was a Constant, so its callers had no edge
A catch (f) parameter and a for loop variable are scoped to their clause (nw-800)f() inside them no longer binds a same-file f
An unparenthesised arrow parameter (f => f()) is scoped to its arrow, like (f) => f()[1].map(g => g()) no longer gives a false edge to an imported g
ESM import bindings are hoisted to the top of their scope (nw-803)A function written above an import sees the binding. A function above a CommonJS require sees it too, including an expression-body arrow (const fb = () => f()); top-level code above the require does not
TS import x = require('m') and export import x = require('m') bind like an import (nw-801)Calls through x resolve. A bare call on a whole-module binding (x()) is unresolved
.ts and .tsx keep their own type bindings (nw-805)type_aware edges are deterministic; on mixed .ts/.tsx repos they may differ from 12.0.x
A broken file with no real symbols gets no owner; a lowercase JSX tag (<div/>) never mints oneSuch files stay disclosed as parse errors and add no empty owners
A top-level call through an import written below a one-line function resolves (JS/TS/Python/PHP), and a sibling's nested homonym no longer hides the caller's own nested functionThose calls keep their edges
A member access or call through an imported receiver (Modal.latestProps after import { Modal }) never binds a same-file symbol of the member's nameThe false self-ACCESSES edge in a file named like its import (Modal.test.js) is gone
.mjs/.cjs files are indexed as JavaScript and .mts/.cts as TypeScript; an extensionless import also reaches them, a directory import reaches its index.mjs/.cjs/.mts/.cts, and index, main, app and server files in those extensions are entry files like their .js/.ts twinsThose files, and the calls into them, appear in the graph

Generation 11 (nw-787, nw-789) scopes a nested JS/TS function declaration to where it is visible, stops a bare JS/TS call binding a method or accessor, scopes a Python def nested in a function to that function, and gives a nested class's members MEMBER_OF their own class (parsed cache 7). Graphs indexed at generation 9 or 10 need the same forced re-index.

Generation 12 resolves imports by package instead of by file name, and resolves more method calls (parsed cache 8):

ChangeEffect on the graph
Go imports read go.mod, go.work and local replace lines, map an import to every non-test file of the package, and honour import aliases. Files marked //go:build ignore (or // +build ignore) are left out of package resolutionCross-package calls in a real Go module resolve; they did not before
Go methods carry their receiver type (MEMBER_OF edges), and every build-tag variant of a function is a callee (except ignore-tagged files)Typed Go method calls resolve, and Type::method names look up
Python from . import mod, from pkg import mod as m, import pkg.mod as m and aliased re-exports through __init__ bind the submodule or definitionThose calls gain edges
Kotlin and Java imports resolve through the declared package (any file of it, wildcard imports, nested classes), not a file named after the symbol, with the language's precedence: a single-type import, then a type in the same package, then an on-demand (*) import. A single-type import brings in only the declaration it namesImports of classes in differently named files resolve, and a same-package type is no longer shadowed by a wildcard import
A method called on a call or new receiver (new K().m(), K.make().m(), chains) resolves through the declared return type. Where the receiver is not typed, a method links only when its name is unique in the repository AND every step of the receiver chain has a repository return type (or plainly returns Name(..), new Name(..) or cls(..)) that is the method's owner or a subtype, so A.find().get() on an Optional, .size() on a List or .then() on a Promise does not link to a same-named repository method. Kotlin/Scala expression-body factories, Ruby implicit returns, multi-line returns and methods returning self are deliberately not typedMore method calls gain edges, conservatively; library-typed chains stay unlinked
new Foo() links the class in Java, C#, PHP, C++, Scala, Groovy and Dart; Rust trait default methods and turbofish calls resolve; a bare TS/JS @decorator references its functionConstructors, trait defaults and decorators are no longer unreachable
Duplicate JS/TS this.x = properties collapse to one symbol, and a bodiless Rust mod x; no longer owns the lines below itFewer duplicate symbols and no false IMPORTS edges

Generations 13–17 add nested Go module and receiver ownership, typed slice range elements, inferred slice and named-return forms, factory-call receiver origins, recovery when package members are recreated, and correct if/switch/case binding lifetimes. 12.2.3 includes all of these changes (parsed cache 11). Existing missing edges require the forced re-index described above.

All these kinds of staleness have the same remedy and the same symptom list. Until you re-index:

  • Rankings are stale. hubs, bridges, repo-map, clusters, and every PageRank-ordered result are computed over edges the old resolver wrote.
  • MEMBER_OF edges are missing for C and C++ members, so reachability under-counts. dead-code refuses to answer on such a graph and exits 2 rather than printing a deletion list built from missing edges.
  • C++ IMPORTS edges are missing. The resolver used to extract #include and then discard it.
  • .h headers were parsed with the C grammar, which has no class keyword. Re-indexing routes them to C++: on a real 874-header corpus, header symbols went 7,166 → 17,872 and class definitions 0 → 1,373.
nestweaver index --repo <path> --force   # per repo — a full index, not incremental

--force is required. A generation-stale repo is sitting exactly at git HEAD with every file unchanged, so plain nestweaver index --repo <path> takes the incremental path, reports 0 added, 0 modified, 0 deleted, writes nothing, and leaves the repo on the old generation. Only a full re-index rewrites the edges.

Vaults are not Repo nodes and carry no resolver generation, so the forced re-index does not touch them. When crossing the 12.2.4 Markdown derivation change, run one brain refresh <vault> per vault to re-derive links against the rebuilt code graph.

stale-check detects this as of 9.0.0. A repo whose edges predate the running resolver reports status: "outdated_resolver", needs_reindex: true, and the command exits 2 — the same code it already used for stale/incomplete/missing, so an existing CI gate catches the upgrade with no edit:

nestweaver stale-check                    # [OLD-RESOLVER] rows + the remedy, exit 2
nestweaver stale-check --json             # "resolver_stale_repos": [...], per-repo "resolver_stale"
cat <db>.resolver_generation.json         # per-repo generation; anything that is not the current one is stale

In 8.x it did not: the status ladder was missing/incomplete/SHA-behind-HEAD only, so a generation-3 graph reported ok and exited 0.

Generations 5 and 6 turned on PERSISTED PER-SYMBOL COLUMNS rather than edge shape: is_entry_point and entry_point_kind are read straight off disk, so a symbol indexed as false stays false no matter which binary asks. Generation 6 roots bash and Python top-level calls, Swift main.swift/shebang files, bash trap handlers, and package.json entry points at any depth in a monorepo. Those additions can only ADD reachability roots, so they can only REMOVE symbols from a dead-code list — an un-re-indexed graph over-reports dead code.

hubs, bridges, repo-map, ranking rank and summary --level hub also disclose it (rankings_stale / stale_repos on --json, a warning on stderr otherwise). Other ranking-derived surfaces still do not — clusters, blast-radius, generate-guide, PPR-backed context, and the whole web UI — so on those, absence of a warning is not evidence of freshness.

_meta moved to the payload and lost its nestweaver.io/ prefix

Only affects raw HTTP MCP clients that read result metadata. The CLI, the MCP stdio server and the daemon are unchanged for callers.

Through 8.x the HTTP /mcp boundary stamped provenance onto the outer tools/call envelope under namespaced keys — nestweaver.io/sources, nestweaver.io/scope, nestweaver.io/stale_repos. It is now written once, at the tool layer, as an unprefixed _meta object on the result payload:

// 8.x — outer envelope
{ "result": { "_meta": { "nestweaver.io/sources": ["local"] }, "content": [...] } }

// 9.0.0 — on the payload itself
{ "map": "...", "_meta": { "scope": "local", "sources": ["local"], "stale_repos": [] } }

A client reading result._meta["nestweaver.io/sources"] gets nothing. Read _meta.sources on the payload instead. The payload location is what the server's own initialize instructions have always promised and what both CLI routes already emitted; the envelope was the odd one out, and MCP over stdio sent no provenance at all.

Note that _meta.stale_repos is federation staleness (which upstreams were behind). It is a different population from the top-level stale_repos on hub_nodes / repo_map, which is resolver-generation staleness, and from stale_repos on stale_check, which is behind-HEAD.

Daemon bypass is CI-only

Standard development and distributed binaries cannot honor --no-daemon, NESTWEAVER_NO_DAEMON, or an explicit permit. Refused requests print a warning and keep the normal daemon route.

Only a separate internal CI test artifact may enable direct-store tests. It requires the ci-direct-tests build feature, NESTWEAVER_ALLOW_NO_DAEMON=1, and a GitHub Actions runner context (GITHUB_ACTIONS=true plus nonempty RUNNER_TEMP, RUNNER_OS, and GITHUB_RUN_ID). Ambient CI=true never grants access, including when set locally. This artifact must never be published. Local development, fixtures, debugging, and recovery use the daemon; setting CI locally is not an exception. See release fixture instructions.

Note that hubs --json carries two different stale_repos: the top-level one is resolver-generation staleness, and _meta.stale_repos is federation staleness (repos where the local index is behind an upstream server). They answer different questions and can disagree.

Also changing behaviour in this release, in ways a script may notice:

ChangeWhat to do
Re-index and refresh required (12.2.2). RESOLVER_GENERATION moves from 11 to 12 and the parsed cache from 7 to 8 (Go, Python, Kotlin/Java import resolution; method calls on call or new receivers; new Foo() edges; see the generation 12 table above). The filemeta and resolution-deps sidecars move from 4 to 5, so the first index after upgrading rebuilds in full. Vault link fixes (frontmatter [[wikilink]] relationships, [[Note#^id]] block references) apply only when a vault is re-derived, and the Markdown derivation version did not change, so that does not happen by itselfRun nestweaver index --repo <path> --force once per repo and nestweaver brain refresh <vault> once per vault; until the re-index stale-check exits 2, dead-code refuses and blast-radius misses the new edges
affected-tests diffs one repository. With --base-ref it is the indexed repo checked out at the working directory's git root; with --files it is the only indexed repo, and when several are indexed the new --repo <name or UID> is required (exit 64 otherwise). Repo-relative paths resolve only in that repo, and --json names it. MCP affected_tests takes repo the same way and refuses files/changed_files together with base_ref (it used to ignore base_ref)Pass --repo (MCP repo) when more than one repo is indexed; send either changed files or a base ref, not both
daemon status exits 69 when the daemon is unhealthy (running but unreachable, or an owner it cannot verify). setup attempts every tool and exits non-zero if any failed. remove-repo with an ambiguous name exits 3. An empty query argument exits 64, and so do pre-push-impact with a bad --format or --min-severity, list-features without --config and interactions show with no arguments. memory consolidate --apply with nothing to apply exits 0. A database error under --json prints a JSON envelopeTreat 69 as "restart the daemon" (nestweaver daemon --db <db> restart), 64 as a usage error
An explicit read-symbols --root (MCP root) must be inside an indexed repository or vault, or a linked worktree of one. A body read never follows a symlink out of the repository, and the web /source route walks from the repo root without following symlinksOmit --root, or point it at the indexed checkout
Git runs isolated for every repository NestWeaver reads, including pre-push-impact --local-changes, the code watcher and blast-radius. The repository's core.fsmonitor, hooks, clean/smudge/process filters, textconv and external-diff drivers, core.askPass and signature verification never run; a repository whose driver configuration cannot be listed is refused. Working-tree status/diff calls pass --ignore-submodules=dirty, so a submodule's own filters never run either (a moved gitlink still counts as changed; submodule contents were never indexed). A file a repo-local filter (for example Git LFS installed with --local) would have normalised may now show as modified in change detectionNothing to change for normal repositories; expect LFS-tracked files to appear modified where a filter used to hide the difference
Git metadata a repository borrows from another (a forged .git/commondir, a gitfile into another repo) is refused, and such a layout never takes the other repo's identity. /proc, /sys, /dev (at any depth) and other system roots are refused as repo or vault roots, and an instance id containing /, \ or .. is rejectedIndex the real checkout, not a path through a pseudo-filesystem
An unreadable source in a language that cannot carry API contracts is skipped and disclosed (read_error row, coverage_status: "degraded") instead of failing the index or watcher batch. An unreadable JS/TS/Java/Kotlin source still fails closed, because skipping a controller would publish an incomplete contract set. A file that vanishes mid-scan is a deletion. A malformed OpenAPI spec that never published contracts is skipped and disclosed instead of failing every indexGate on coverage_status / --fail-on-skip; fix the named file's permissions
Edits to .gitignore, .ignore and .git/info/exclude are reconciled: newly hidden sources leave the graph and newly visible ones are indexed, at watcher time and at startup. Global-excludes patterns with a slash are anchored at the repo root. A watcher that cannot publish, an interrupted vault refresh and an interrupted embedding pass now show in brain status until they finishNothing to change
An incremental index that was killed part-way leaves a per-repo "publication incomplete" record: stale-check reports the repo incomplete and the next index rebuilds it in full. A full index whose bulk-load checkpoint fails now fails instead of reporting success. A daemon whose database file was deleted or replaced refuses writesRe-run nestweaver index --repo <path> for a repo stale-check reports incomplete
Client-supplied lists and values are capped and stated in each MCP tool's inputSchema: context seeds at most 256 (duplicates collapsed), kinds 32, repo/tag filters 100 (1000 for hub_nodes/bridge_nodes), file lists 1000, count_patterns.patterns 64. set_extension: uid 1 KiB (not blank, no invisible format or bidi characters such as U+202E), key 256 bytes, value 64 KiB of JSON nested at most 64 deep, no control characters, the sidecar written as compact JSON, last_indexed_at reserved, node and property counts capped. brain_add_source names: 1-255 characters with no control characters (CLI and store too; an already-stored bad name is listed escaped and can be removed by path or UID). MCP stdio frames are capped at 64 MiBSplit oversized requests; read the limits from tools/list
brain_remove_source refuses a target that matches sources of different kinds (a repo and a vault sharing a name) or several sources, with candidates; repo URLs match exactly (no suffix match). It also accepts the derived repo name the other tools use. prune_stale removes a source only when its root is not found; an unreadable root is kept with a warningRetry with a UID from candidates
Metadata writes (set_extension, unset_extension, interactions forget) wait at most NESTWEAVER_METADATA_WRITE_WAIT_SECS (default 15) for the write lock, then answer write-busy; a cancelled request is never applied. MCP count_patterns has one max_millis budget for the whole call (default 10 s), shared by all patterns, and marks a pattern it cut truncated: true with lower-bound counts. The CLI's count-patterns takes the same budget as --max-millis (1-600000) and, when the budget cuts any pattern, prints a stderr warning and exits 75 (EX_TEMPFAIL) instead of 0Retry a write-busy answer; raise max_millis (--max-millis) for a large pattern set, and treat exit 75 as lower-bound counts
brain_context and brain_search rank an exact-case symbol match first and apply repo filters before the result cap. regex_search without a trigram index finds what count_patterns finds. blast_radius gives the same risk on identical calls. Concise MCP rows keep uid and location, so they are largerNothing to change; budget for slightly larger concise responses
New response fields: missing_sections (note_get), did_you_mean_by_target (read_symbols), changed_symbol_count, proposals_already_applied (brain_memory_consolidate, whose limit is now applied before any proposal moves), refresh_vault_paths, truncated on pattern counts, and publication_in_progress. note get, backlinks and MCP note_get resolve a path-qualified title without .md; [[Note#^id]] block references resolveRead the new fields where useful; they are additive
contracts diff reports parameter and response-status changes, and --fail-on-breaking fails on themReview the newly reported changes before gating
The CLI sends the daemon absolute --config, root and backup save paths, and the daemon refuses relative ones. watch-stop no longer starts a daemon. Tracing respects --no-color, NO_COLOR and non-TTY stderr, and an invalid numeric NESTWEAVER_* value warns once instead of being silently ignored. Terminal control sequences from indexed content are escaped when stdout is a terminal. Secret env var values no longer appear in --helpNothing to change
backup save --force refuses a destination that is the live database or one of its files (also through a symlink or hard link), and backup restore --force replaces only a NestWeaver data directory. config validate checks that fusion weights sum to 1.0, rejects duplicate repos and caps the file sizePick a backup path outside the database's files
setup was checked against each tool's documented config location: VS Code and Copilot get .vscode/mcp.json under servers; Continue gets .continue/mcpServers/nestweaver.json; Kiro .kiro/settings/mcp.json; Cline gets a printed snippet; Aider's invalid repo-map: line is gone. Hook commands quote an absolute --db. A changed --db is reported and --force rebinds it. setup refuses to write through a symlinked directory outside the project. The Claude Code hooks (shipped and installed) now read tool_input and return hookSpecificOutput, so they actually fire; re-running setup claude-code repairs an older installRe-run nestweaver setup after upgrading
hooks --install takes --db (written into the hook as an absolute path) and never writes through a symlink. Run from a subdirectory, it binds the repository root's database. It mentions core.hooksPath only when that is set. --uninstall restores the newest backup only when the installed hook is NestWeaver's; otherwise it leaves the hooks alonePass --db when the database is not ./nestweaver.lbug
The code watcher now resolves each batch with the full index's resolver over the whole-repository view, so a watcher-maintained graph matches a fresh index (re-exports through __init__.py and type-aware member calls used to be lost on large batches). A file the batch cannot re-parse keeps its edges. The daemon keeps one parse cache per database in memory and refreshes it each batchNothing to change; expect somewhat higher daemon memory on large repositories
Claude Code integration: the shipped search hook searches the grep/rg pattern, not the path. The Bash hook setup installs fires only when grep, rg, find, fd, ack or ag is the command actually invoked, and does nothing without jq. setup recognises only the exact hook commands it writes, so a user's similar-looking hook survives a re-runRe-run nestweaver setup claude-code to refresh the hooks
setup trae, setup devin and setup hermes write .trae/config.json, devin.json and .hermes/config.json. Those paths are not where the tools read MCP servers (Hermes reads mcp_servers in ~/.hermes/config.yaml; Devin reads .devin/mcp_config.json or ~/.config/devin/mcp_config.json), so the registrations are ignoredRegister NestWeaver by hand in those tools' own config until setup is fixed
Interaction memory (--track-interactions) is now a re-rank, not part of the walk. A node the query's walk reached is scaled by at most +5% by how often agents used it; a node the seed cannot reach stays out, however often it was used. Results a query only showed no longer count toward the three-session floor, and the end-of-session success signal reinforces only results the agent then opened (B3). Before this, interacted nodes were teleport targets, so context could list dozens of unrelated symbolsOptionally run nestweaver interactions clear once to drop sessions recorded under the old rules, whose shown-only results still carry a floor
MCP brain_impact sends its dependents once, as impact_nodes; the duplicate nodes list is gone from MCP (the CLI --json keeps both). A cut made to fit the output budget is disclosed in output_budget.cuts, and truncated_by_limit is set only when limit was the cause (M3)Read impact_nodes
A repo filter that names no repo (hubs --repo nosuch, every --repo listed below) writes "error": "not found" in --json, the word every other not-found envelope uses; it was "not_found". status still reads "not_found" (B6)Branch on status, or on error == "not found"
New exit codes: summary --level <invalid> exits 64 (was 1); summary --target matching nothing exits 2 with a not-found message and envelope (was 0, "graph may be empty"); context --feature <name> naming no [[features]] entry exits 2 and suggests declared names in did_you_mean (was 1); investigate-expand resolving none of its targets exits 2 (a partial resolution still exits 0); investigate --scope project:<unknown> exits 2 and a malformed --scope exits 64, each reported once instead of inside an "Internal error" (B9, V4)Treat 2 as a miss and 64 as a usage error
pr-impact reviews one repo: the indexed repo checked out at the working directory's git root, or the one named by the new --repo <name or UID>. A repo-relative --files path now resolves in that repo only, not in every indexed repo with a file at the same path. When neither names exactly one repo every repo is matched, as before. --repo keeps its class on both routes: not found 2, ambiguous 3 (with candidates), over 512 bytes 64. An empty --repo '' is ignored (every repo is matched), and a selector that names nothing, such as repo:::, is not found (2) (B4)Run pr-impact from the repo under review, or pass --repo
Web: a <module> owner reads path::<module> in /api/v1/symbols/top (name and display_name), overview landmark labels, search hits (name, title, display_name) and snapshot.msgpack node names; the Cypher export keeps the raw name and adds a display_name property (R1, B5)Read display_name where present; do not treat name in these responses as the raw symbol name
brain status reports the daemon's manifest reconciliation as manifest_recovery (state, attempts, retry_after_seconds, error) and warns while it is deferred, retry_scheduled or blocked. A capture slowed by contention defers the rebuild and refuses no repo; a repo that runs out of its own 60 s budget on 3 passes in a row is refused with a contention: reason (no index --repo remedy needed) and the other repos publish. The write gate is held for at most 60 s of captures per reconciliation (D3). The text output shows the state tooNothing to change; a contention refusal clears itself once the repo captures in time
A watched vault batch that collides with another writer's transaction retries with backoff (2575 ms in all, the write lease released while it waits). If the collision outlasts the retries the batch's notes are owed and replayed on the retry backoff and at the next start, instead of the watcher exiting; brain status lists them under "Watcher reconciliation pending" and shows the daemon's last_watcher_failure, which now survives the watcher's restart (also in text) (V1)Nothing to change; nestweaver brain refresh also replays owed notes
A note-to-code relink no longer forces a PageRank recompute on every ranked read: the code-only ranks stay warm and .pagerank.json is rewritten at the new generation (D1)Nothing to change
A database error is called corruption more carefully. A write-transaction collision, an index publication in flight and a busy daemon are never corruption. A file shorter than its catalog read while another process writes says so and names the next step (if it repeats, nestweaver daemon --db <db> stop and re-run); an engine assertion or an unclassified corruption is corruption whether or not the daemon is up, and so is a truncation reported inside a timed-out health check or a refused publication (V2)Follow the step the message names before restoring a backup
investigate answers through a live watcher batch with publication_in_progress, but does not save that map as a bundle: the result carries bundle_not_saved (also printed in text) and its bundle_id cannot be expanded or hydrated (V4, I3)Re-run investigate once the batch finishes to get a bundle to drill into
A call a JS/TS/Python/PHP file makes at its top level, outside every function, class and method (a bare call, an IIFE, an Express-style route handler, a decorator, a __main__ guard, a top-level await), is now owned by a per-file <module> symbol (Module, entry point module_init). impact shows it as the caller, dead-code treats it as a root (so a function called only at module load is no longer listed, and <module> itself is never listed), and a one-line function above such a call no longer owns it. An owner that calls something is its own process, named <repo-relative path>::<module>, so detect-changes lists more processes in repos with decorators, route registration or top-level test setup; an owner with no outgoing CALLS is not a process. Name search hides <module> unless you search for exactly <module>. Resolver generation 10 and parsed cache 6 (nw-113)Run nestweaver index --repo <path> --force for each repo after upgrading; search <module> by its exact name
Module owners are labelled <repo-relative path>::<module> everywhere (impact rows, read-symbols, context, flow-trace, investigate neighbours, ambiguity candidates, process names, Mermaid export, the GraphML label, the web UI). symbol --json keeps each symbol's raw name and adds a labelled display_name to the symbol and every caller and callee. A file that is only top-level code gets a summary --level file line with no exports 0 symbols clause, and no line at all when that code calls nothing indexed in another file. read-symbols, impact, flow-trace and context look one up as path::<module>; the path is the exact repo-relative path or a suffix on a / boundary (app.js, or conftest without the extension), and a suffix that several files share is ambiguousName an owner path::<module>; lengthen the path when it is ambiguous
A qualified name now narrows every name lookup, not only owners. The segments before the name are read two ways and both readings are kept: the first as a file (an exact repo-relative path, a suffix on a / boundary, or that suffix without its extension, such as conftest) followed by a class chain, or all of them as a class chain. So path::name works, and Class::method and path::Class::method work when the index records the method as a member of that class. A Rust impl block in a different file from its struct is not recorded that way, so Struct::method is not found there; its Did you mean: line names the path::name that resolves. Outer::Inner::method works in Java and C#, where a nested class is a member of its outer class. Python nested classes and TypeScript namespaces are not recorded as containers, so there it is not found, with the same not-found message. A class name that is also a file stem (Svc::run with a/Svc.ts and a class Svc in b.ts) is ambiguous rather than answered by the file. A leading / is ignored and \ reads as /. impact, flow-trace, symbol, context, brain context, context --feature entry points and MCP brain_context all resolve qualified names this way. A qualifier that names neither is not found (exit 2), where it used to resolve by the last segment. Every one of these commands answers such a miss the same way impact does: a Did you mean: line of path::name specs (path::Class::method for a member) on stderr, and did_you_mean in the --json not-found envelope and the MCP envelope. Suggestions are substring matches first, then names a small typo away (edit distance up to 2; up to 1 for a 3- or 4-letter name), and a path::name whose path names a file is answered from that file's members (the close ones, else all of them in source order). read-symbols and MCP read_symbols answer a miss the same way: not found (exit 2) with the Did you mean: line on stderr and did_you_mean in JSON and MCP. Before calling it a miss they try shorter readings that are still qualified, dropping the outermost qualifier each time (zzz::Svc::run reads as Svc::run), and say so when one answers. A leading qualifier that could be a file (it has a / or a ., or an indexed file has it as its stem) is never dropped: nothere.ts::Svc::run is not found, and the shorter reading that does answer (Svc::run) is the first did_you_mean entry, so another file's Svc::run is never read in its place. When one is dropped they say so: a warning: line on stderr and a qualifier_ignored entry (query, note) in JSON and MCP. They never fall back to the last segment alone, and a path::<module> is never shortened: a file with no top-level calls has no owner, so its path::<module> is not found rather than a list of every owner in the graph. Ambiguity candidates carry file_path, and each ambiguity carries a hint that only offers what tells the candidates apart: "pass a UID or path::Class::name" when each candidate has its own class, "pass a UID or path::name" for an unqualified name whose candidates are each in their own file, "pass a UID or path::Class::name" again when candidates share a file but a class tells them apart, and otherwise "pass a UID"Qualify a name as path::name or Class::method, or pass a UID
Module owners are callers only. They are left out of clusters, repo-map and investigate entries; of the changed-symbol lists and counts of detect-changes, affected-tests (including its tier-1 test count), pr-impact, brain diff and pre-push-impact; and of embeddings and vector search. An owner that calls a changed symbol is still reported as affected. A detect-changes process listed only because a member file's top-level code changed has affected_symbol_count: 0 (owners are not changed symbols) and carries top_level_code_changed: true to say whyNothing to change
context, brain context and context --feature rank owners after every real symbol and list at most 3. The rest are counted in module_owners_omitted (JSON and MCP), printed as "+N more files' top-level code", and left out of the totals; when an owner is listed or left out, each command's Connected (...) heading says so and how many (… owners listed last, N more not counted); otherwise the heading is unchanged. Owners the --limit cuts are counted the same way. When owners are hidden, by the cap or because so many files call the seed at load time that the owners sink under the walk's usual relevance floor themselves, their places are refilled with real symbols the walk scored under that floor (at most as many as owners were hidden, never past --limit), so a helper called at load time from many files keeps its real neighbours; the totals count themRead module_owners_omitted
summary --level symbol and MCP get_summary list every real caller but at most 3 owner callers, then +N more files' top-level codeNothing to change
dead-code seeds its walk from owners but counts them in neither "entry points" nor "excluded"; --json gains module_owner_roots. A walk seeded only by owners is not degraded: coverage needs entry_points + module_owner_roots > 0. With --repo (MCP repos) both counts are that scope's own roots, like the other totals; coverage still asks whether the whole-graph walk had any root, so a library reached only from another repo is not degraded. --json (and MCP) carry that whole-graph count as walk_roots, and the text warning "no entry point was found" is printed only when walk_roots is 0Read module_owner_roots beside entry_points
read-symbols path::<module> returns the file's top-level code: the lines outside every function, class and method, with each elided body shown as ⋮Nothing to change
pr-impact, blast-radius and detect-changes report a changed source file that is only top-level code (a script, a seeder, an entry file) instead of a silent Low with nothing changed: a changed-file-top-level-only warning (on all three) names its path::<module> owner and the first 10 symbols that code calls (+N more after that). Files that load it only for its side effects (import './x', a bare require) have no edge in the graph, so the warning says its importers were not assessed and the run is partial with gate degraded-unknown. In pr-impact and blast-radius JSON the callees are listed apart in top_level_callees (edge_type: TOP_LEVEL_CALL, depth 1). They are not dependents, so they stay out of affected_symbols, affected_symbol_count, the clusters and the risk level, which is Low unless the file has real dependents. The owner is still not a changed symbolRead top_level_callees as what the changed top-level code calls, not as dependents; check the file's side-effect importers by hand
affected-tests selects a test file whose own top level calls a changed function. When none of that file's tests was reached, its tests list is empty and selected_by: "top_level_code" (JSON and MCP) says why; it counts as one test, so the summary never reads 0 beside a selected file, and the text output shows it as (top-level code). A test file that only imports the changed module, without calling it, is not selectedNothing to change
affected-tests lists each test file once, in the best tier any of its tests reached, with all of its affected tests there (nw-799). A file used to appear in both tier 1 and tier 2Count files per tier, not tests
read-symbols --token-budget (MCP token_budget) cuts a first symbol larger than the budget to its leading lines, closed by a marker line, and sets body_truncated: true; it used to return it whole. The text output then ends with body truncated to fit the token budget, not truncated: 0 symbol(s) dropped. A budget of 0 still returns the first symbol wholeCheck body_truncated before treating a body as complete
After an edit, the watcher and incremental index always re-resolve a changed file's direct importers; the 200-file cap now bounds only the transitive expansion. Past 5,000 direct dependents the pass is skipped with a warning naming index and index --force; past 200 the count and time are logged. Barrel files that only re-export are re-resolved too, so their reexport_resolved edges survive editsNothing to change
A nested JS/TS function declaration binds only where it is visible: inside its enclosing function (including nested functions and callbacks there) and, in strict code (TypeScript, an ES module including any .mjs/.mts file, a "use strict" directive in the file's or an enclosing function's prologue), only inside its block. A call before it in that scope still binds it (hoisting); a module-level declaration still binds file-wide. A Python def nested in a function binds only inside it. A bare JS/TS call never binds a method, getter or setter (this.x() and obj.x() are unchanged), so a same-named free function wins. A nested class's members are MEMBER_OF that class, not a same-named top-level one. The full index and the watcher now agree on all of these (nw-787, nw-789)Calls that bound a sibling's nested function, a block function after its block, or a same-file method now bind the import, the caller's own function or nothing. Re-index with --force (generation 11)
The index CPU budget (NESTWEAVER_INDEX_CPU_PERCENT) is off by default (nw-814). It was added because macOS was believed to kill a daemon using 90s of CPU in 180s; it does not. macOS's CPU usage monitor is per thread, armed only by a spawner that asks (launchd does), and non-fatal: it writes a *.cpu_resource.diag report ("Action taken: none") and the daemon keeps running. Parse workers still run at utility QoS on macOS, which keeps the machine responsive. An explicitly set 1–40 still applies the budget, with 1–11 raised to 12 (the smallest budget with room beyond the 20s write reserve); 41–99, including an older plist's 50, mean offNothing to change. To keep a budget, set NESTWEAVER_INDEX_CPU_PERCENT to 12–40 and re-run daemon start so the launchd plist carries it
daemon gc also prunes the authority registry (~/.local/state/nestweaver/authority), which grew one lock record per database scope ever locked (nw-811). It removes records whose database, publication root or operation journal is gone, and empty records from earlier releases that are older than 24h, unheld and match no live database; a record some process holds is never removed. --dry-run reports what would go and changes nothing (it skips the launch-agent and directory sweeps). --db X limits the prune to X's records and leaves the older empty records alone. A registry gc cannot sweep is a warning, not a failureRun nestweaver daemon gc --dry-run to preview, then nestweaver daemon gc
A watcher pass over a file with a class keeps its MEMBER_OF edges and resolves this.m() / self.m() as type_aware, as a fresh index does. Before, it dropped every MEMBER_OF edge of the edited file, so dead-code on a watcher-maintained graph could list constructorsNothing to change; graphs kept by an older watcher regain the edges on the file's next edit or a --force index
A code watcher keeps running when a committed batch's evidence cannot be saved. It notifies the committed graph and discloses the outstanding repair, retaining replay paths in memory across retries. Successfully persisted replay debt also survives restart; startup repairs imports across bounded source batches.Restore access to the reported evidence files and let the watcher retry. If replay debt itself could not be persisted, keep the watcher running until repair completes; after interruption, run nestweaver index --repo <path> --force to rebuild missing evidence and relationships.
Rebuild required. LadybugDB 0.21 (0.21.2 in published 12.2.4) changes how text keys are hashed and its on-disk format marker did not change, so NestWeaver now refuses a database built by an earlier version before opening it: exit 1, nestweaver::db_rebuild_required, the exact rebuild command, no daemon started, no byte changed. Snapshot format is now 4; older snapshots are refused, and backup restore of a pre-upgrade archive warns that the result needs a rebuildStop the daemon, run nestweaver backup save <file> (it reads the old database read-only and marks the archive as pre-upgrade), then nestweaver publication rebuild --config <instance.toml>; the old database stays in place until the new one validates. To roll back, reinstall the previous version and restore your backup. Do not open a rebuilt database with an older NestWeaver. See docs/guide/publication-rebuild.md
A daemon killed by a fatal signal (SIGSEGV, SIGBUS, SIGABRT, SIGILL) while answering is now named. A database with damaged index pages can open under LadybugDB 0.21 and fault on a later lookup; the command used to print a bare transport error … broken pipe, and the respawned daemon reported a healthy brain status. The command now exits 1 with nestweaver::daemon_engine_crashed and the recovery, MCP tool calls return the same message with isError: true, and brain status prints a warning (--json: a warnings[] entry of kind daemon_unclean_exit with exit, signal, at_unix, pid, count). A daemon killed from outside (kill -9, the OOM killer) is reported as exited_unexpectedly, with no claim about the storage engine. daemon stop (with or without --force), Ctrl-C on a foreground daemon run and an idle exit leave no warning, and the warning clears when a daemon next shuts down cleanly. Nothing in the database is changedRestore the most recent backup with nestweaver backup restore <archive>, or rebuild with nestweaver publication rebuild --config <instance.toml>. Do not retry the request that crashed: it will crash the daemon again. See Troubleshooting
Renaming a registered vault with --name (brain add <root> --name X, brain refresh <root> --name X, brain watch, MCP brain_add_source) is now refused, exit 1, when another root's vault already holds that name (case-insensitively), with the same message and remedy as registering a new root under it. It used to succeed and leave two vaults answering to one name. Without --name, brain refresh, brain watch, brain add and MCP brain_add_source now keep a registered vault's stored name instead of renaming it to its directory's (a new vault is still named after its directory)Pick a free --name, or remove the other vault first
brain context --kinds and --intent, and context --intent, now refuse a value outside their fixed vocabulary at parse time with exit 64 and a message naming the valid values (they exited 1 with an internal error). MCP brain_context, regex_search and count_patterns report an unknown kind as an invalid argumentFix the flag value; the message lists the accepted ones
Every repo filter now resolves through the one repo resolver and keeps its failure class: clusters --repo, dead-code --repo, brain context --repos, investigate --scope repo:<name>, cross-repo-contracts --repo, impact --repo, flow-trace --repo, contracts list --repo, contracts drift --repo and service-summary --repo exit 2 (status: "not_found") for a repo that is not indexed, 3 (status: "ambiguous", with candidates) for a name several repos share, and 64 for a selector over 512 bytes. A malformed selector such as repo::: names no repo and exits 2. An empty --repo '' exits 64 on hubs, clusters, dead-code and affected-tests, but impact, flow-trace and pr-impact ignore it and match every repo. dead-code, brain context and cross-repo-contracts used to exit 1 with an internal error; clusters --repo on the daemon route reported an ambiguous name as not found; investigate --scope repo:<name> matched repo UIDs by substring and merged every match, so a fragment that matched only a repo UID (not its name, URL or root) now misses; impact/flow-trace --repo fell back to substring matches on file paths and UIDs. Over MCP a repo filter that names no repo is isError: true with the not-found envelope, and an ambiguous one names its candidatesBranch on the exit code, or on status in the JSON envelope; pass a repo UID or root path to pick one of several same-named repos
A wikilink that exactly and uniquely names a note (case-insensitive, any folder: its filename stem is unique in the vault and no other note has that title) now resolves at confidence 1.0 and is no longer reported. brain broken-links, MCP brain_broken_links, memory lint's broken_wikilinks (and broken_wikilinks_total) and doc-stats now count only BROKEN links: unresolved (0.0) or ambiguous (several notes match; rows gain candidate_count). Links that resolved to one note by a fuzzier tier (a shared stem narrowed by folder, a path whose basename alone matched, an alias) move to a separate list that is not broken: broken-links JSON low_confidence is now that array (was a count; the count is low_confidence_total, with low_confidence_truncated), and ambiguous is added; total/returned/truncated describe broken links only, and offset/limit window both lists. memory lint gains low_confidence_wikilinks (+ _total); doc-stats gains ambiguous_link_targets, and low_confidence_link_targets no longer includes ambiguous linksRead low_confidence_total for the old count; gate on total (or unresolved + ambiguous) for broken links. Existing vaults are re-resolved automatically: the Markdown link derivation version moves to 2, so the daemon re-derives each vault once in the background (or run brain refresh <vault>)
A resolver-generation-stale repository now degrades blast-radius / pr-impact, detect-changes and affected-tests only when it owns a changed file, or is reachable from a repository that does through any chain of recorded or declared repo links (any symbol-to-symbol edge, or a [[links]] entry, in either direction). Any other stale repository is disclosed in a resolver-generation-stale-unrelated warning notification (naming it and the index --force remedy) and no longer degrades the gate, refuses affected-tests, or appears in resolver_stale_repos, which now lists only the repositories that degrade the answer. Declared links count when the daemon or MCP server was started with --config, and on the direct CLI route from --config or else the config the database's daemon last started withGate on resolver_stale_repos / gate_state as before; read the resolver-generation-stale-unrelated notification to find stale repositories elsewhere, or run stale-check
The 409 for an empty seed container on POST /api/v1/brain/context carries the CLI's coded body, {"error": "seed container is empty", "status": "empty", "message"}. The remedy fits the container: add notes to a vault, re-index a repo that has no symbolsBranch on error: "seed container is empty"
investigate-expand / investigate-hydrate on an unknown or expired bundle exit 2 (was 1), and --json writes {"error": "not found", "bundle_id", "message"}Branch on exit 2, then run investigate again for a new bundle
Every web API error body is JSON {"error": …}: axum's own rejections (a query parameter or JSON body that does not parse, a body over the limit, a wrong method) used to answer text/plain (or an empty body), and an unknown /api/… path answered an empty 404. Statuses are unchanged. Outside server mode, /admin/api/* on the UI is a JSON 404; it used to serve the SPA's HTML with 200Parse error bodies as JSON
A declared project repo removed with remove-repo (or indexed since the last materialization) is now disclosed, or cleared, by the daemon's next code-link pass: list-projects and project-context print Warning: declared repo not a member: … without waiting for materialize-projectsNothing to change
brain status names a project whose declared repos resolve to none by its name, not its uid; --json code_links gains unscoped_project_names (index for index with unscoped_projects). notes_changed_as_of, printed as "as of the last pass", is now re-dated by every pass that finds changed notes; it used to keep the date of the first pass that saw themNothing to change
list-projects lists each project's member repos: a Repos: line in text ((none) when it has none) and a member_repos object (project name to [{uid, name}]) in --json. The daemon's project listing carries them as repos on each projectRead member_repos instead of calling project-context per project
cluster <id> with an id no cluster has prints a bounded hint on stderr (the count, the id range, the ten largest, and nestweaver clusters) instead of every cluster (2.2 MB on a large graph); still exit 2. ranking rank <missing> --json now writes the {"error": "not found", "symbol": …} envelope on exit 2 like the other read commands, and nestweaver --help no longer names a nonexistent rank commandRun nestweaver clusters for the full list
investigate-expand / investigate-hydrate without --json now print text on the daemon route too (they printed JSON whether or not --json was passed); an entry with no body prints (body unavailable: <reason>). When a symbol's repo was indexed at a checkout that has since moved, the reason now names that recorded path and says it no longer exists, instead of "no recorded local_root". The bundle-cache warning of all three investigate commands now suggests --root / --db, not --repo / --config, which they rejectPass --json for machine-readable output
POST /api/v1/context and /api/v1/brain/context refuse a blank seed ("" or whitespace) with 400, as the CLI and MCP already did; seeds: [""] used to answer 200 with arbitrary results. /api/v1/context now shares the 100-seed cap, and both routes cap the request body at 64 KiB (413 past it)Drop blank seeds before sending
GET /api/v1/brain/notes?after= must be a note uid of the listed vault (note:<vault uid>:<hash>, or any note:vlt:…:<hash> without vault=). Anything else, including an empty or double-encoded cursor, is 400. It used to restart silently at page 1 or return an empty "end" pageSend back the X-Next-After value decoded once
A context seed that names a vault with no notes (or a repo: with no indexed symbols), and nothing else, is no longer the No seeds resolved miss a bogus uid gets. The engine error starts Seed container is empty:; brain context exits 1 (was 2) and --json prints {"status": "empty", "error": "seed container is empty", "message", "empty_seeds"}; MCP brain_context is isError: true with that text rather than the not_found envelope; POST /api/v1/brain/context is 409 (was 404). A bogus vlt: uid is unchangedBranch on status: "empty" (or 409) to tell an empty vault from a wrong uid
Symlinks in a vault are still not followed (a link can point outside the vault or duplicate a note under a second path), but they are no longer silent: a symlinked directory, or a symlinked file with a Markdown name, is listed in skipped_files / skipped_notes with reason code unsupported and a reason starting symlink to a …. It is a policy skip: coverage stays complete and link derivation is not blocked. A .brainignored link is not listed. The watcher treats a symlink event the same way; a link pointing outside the vault used to fail the whole watcher batch, and one pointing inside was indexed through the linkMove or copy the target into the vault to index it
An indexed note that grows past max_note_bytes now leaves the graph and search on the watcher and brain refresh --since routes too, as a full refresh already did, and is disclosed once as an oversized skip row. It used to keep its old text (still searchable, with its old links) and, when it grew while no watcher ran, was replayed as a full batch on every watcher startShrink the note or raise [indexing].max_note_bytes, then refresh the vault
brain status answers while the daemon re-derives a vault and says so: --json gains vault_derivation.in_progress (vault_uid, root_path, phase, started_at_unix_seconds, elapsed_seconds, indexed_notes; null when none runs) and the text prints Vault derivation in progress: <root> (phase: …). A config file that cannot be reloaded for the repository-eligibility refresh is now a repo_eligibility_unrefreshed warning instead of failing the whole statusRead in_progress to see why link-graph tools refuse a vault for now
MCP: a lookup tool whose target does not exist now returns isError: true with a JSON envelope in both the text and structuredContent: {"status": "not_found", "error": "not found", <target key>, "message", "did_you_mean"?}. brain_impact flips from isError: false to true; flow_trace, note_get, backlinks, cross_repo_contracts, project_context, brain_context/code_context (no seed resolved), investigate_expand/investigate_hydrate (unknown bundle), brain_diff (unknown repo), clusters (a cluster_id no community has; it used to return an empty list) and brain_remove_source return the envelope instead of prose; brain_memory_related and read_symbols with no target resolving now set isError: true, and brain_impact, brain_memory_related and read_symbols misses gain message. Through a daemon with an upstream, a brain_impact miss on both tiers (or the upstream unavailable) carries the envelope at the top of the two-tier result, and a read_symbols miss on both tiers keeps it after the merge. backlinks with a uid naming no note is now this miss (CLI exit 2), not an empty success. Searches that match nothing stay isError: false (nw-557)Branch on isError and read structuredContent.status; retry with a did_you_mean entry
MCP: tools/call with an unknown tool name is now a JSON-RPC error -32602 (Unknown tool: <name>), the same shape as a missing name. It used to be a result with isError: true. Schema-invalid arguments are unchanged: still a result with isError: true (nw-576, nw-700)Handle the JSON-RPC error for a misspelt tool name
clusters --json now uses the MCP clusters envelope: clusters (was communities), total / returned (were total_communities / returned_communities), per-cluster size (was member_count), plus cluster_count, symbol_count and limit (nw-559)Read the new keys; the member lists are unchanged
MCP blast_radius, affected_tests and detect_changes accept files, hub_nodes/bridge_nodes accept top, and read_symbols accepts neighbors, the CLI flag names. Two spellings of one argument with different values (e.g. changed_files and files, limit and top, targets and uids_or_fqns, target and name) are now refused with 'X' and 'Y' are aliases; detect_changes used to keep changed_files silently (nw-558)Pass one spelling, or the same value in both
An empty string for an identifier or query argument (uid, title, name, target, project, symbol, query, pattern, bundle_id, key, tag, path, base_ref), and an empty list or "" entry in seeds, targets, uids_or_fqns or patterns, is now a schema error: MCP isError: true, CLI exit 64. get_summary with name: "" used to return the whole catalogue, and backlinks/query_extensions/brain_memory_related with uid: "" answered success (nw-577)Omit an argument rather than sending ""
regex-search rows gain column (1-based character column on line) and matched (the matched text, at most 200 characters), so several matches on one line are no longer identical rows. The text output appends :COL to path:line (nw-549)Use column to tell same-line matches apart
brain doc-stats text prints one unresolved links: line (per note and target, with the per-section count in parentheses) instead of two lines that read as a note miss and a section miss. JSON and MCP keys are unchanged (nw-554)Update scrapers of the old two text lines, or use --json
brain context <name> --json with no seed resolved (exit 2) now includes status: "not_found" and message, the engine's text naming the nestweaver investigate command to run for a question. The daemon route's text now prints that sentence rather than the RPC wrapper (nw-511)Show message to the user
read-symbols <target> --root <dir> with a --root that does not exist, cannot be read, or holds none of the indexed files (reason no indexed file readable under it) now exits 1 with "error": "unreadable_root" and an unreadable_root object (path, reason, remedy). More generally, a read where every target resolved but no body could be read now exits 1, not 2. Exit 2 now means only that a target did not resolve (nw-539, nw-706)Gate on 1 for unreadable source and 2 for unresolved targets; pass the right --root, or omit it to read from each repo's recorded root
brain refresh gains --json and --fail-on-skip (nw-196). --json prints one object on stdout: vault, mode ("full" or "since"), coverage_status, skipped_count, excluded_by_request_count, skipped_files[] (path, reason_code, detail, observed_bytes, limit_bytes, excluded_by_request), frontmatter_unparsed[] (the same fields without excluded_by_request) and message (the text summary); progress stays on stderr. excluded_by_request is true for a .brainignore match. --fail-on-skip exits 1 when any row is not excluded by request. A vault whose only skips are .brainignore exclusions now reports coverage_status: "complete" everywhere (daemon progress, MCP brain_add_source, brain refresh --json); it used to read "degraded" on the daemon and MCP routesUse --fail-on-skip or the JSON rows to gate on vault coverage instead of parsing the text summary
summary --token-budget N whose first matching summary alone exceeds N now returns that summary and flags it with budget_exceeded_by_first_item (requested_tokens, returned_tokens, note), instead of returned: 0 and an empty list. MCP get_summary does the same. Later summaries are still cut by the budget (nw-644)Check budget_exceeded_by_first_item if a response must stay under the budget
nestweaver mcp --config <file> with an invalid config now answers the client's first request (normally initialize) with a JSON-RPC error naming the file and the parse error, then exits 1. It used to exit 1 with empty stdout (nw-656)Show the JSON-RPC error; fix the config
summary (text) and generate-guide --config/--rules-from are now served by a running daemon instead of opening the store directly, which failed while the daemon held the write lock. generate-guide never sends the config file: the CLI sends only the guide sections as a projection (guide_config: links, features, projects; no tokens, auth, git or URLs) plus the --rules-from contents as rules. Such a request goes to the local daemon only, never to a federated upstream. Each input is capped at 1 MiB (exit 1 when exceeded). MCP brain_guide accepts guide_config and rules; a config path is still refused. An explicit --config must match the running daemon's, as for other commands (nw-690)Start the daemon with the same --config you pass to generate-guide
context <missing> --json still exits 2, but message is now the root cause only, without the code_context RPC failed: code: 'Internal error' wrapper and the repeated text (nw-550)Nothing to change unless a script matched the wrapper text
brain refresh --since now lists its skip rows, and the "NOT marked current" note names the paths that could not be read. A refresh refused because the vault is Blocked names the vault, the directories unreadable now, when the automatic retry is due, and the remedy (a full brain refresh without --since). brain status prints a Vault BLOCKED: <root> line, and the daemon's vault_derivation status gains blocked_vaults[] (nw-694)Run a full brain refresh <vault> to clear a Blocked vault without waiting for the retry
A config-less brain add --instance X no longer breaks brain context after a daemon restart (ForeignRecord): derivation records carry the live instance, and a refresh heals a record stamped with the ambient default (nw-693)Run brain refresh <vault> once on an affected database
The daemon now rebuilds the manifest sidecar (and clears manifest-debt.json) when a repo's recorded eligibility is from the superseded pre-nw-652 fingerprint version; one such repo used to block the rebuild for every repo. suggest-links while manifests are owed now says they are not ready and why, instead of advising daemon start for a daemon that is running (nw-680, nw-700)Nothing to change; re-index a repo named in the rebuild error if the sidecar stays blocked
The local UI rejects a non-loopback Host or mismatched Origin with 403 (nw-682)For a deliberate local reverse proxy, set NESTWEAVER_UI_ALLOWED_HOSTS to its hostname and forward the browser's original Host
UI responses now include CSP, nosniff, frame-denial and referrer headers (nw-625)Allow the UI's same-origin assets when configuring a local reverse proxy
GET /api/v1/source reads only indexed source paths. An unindexed path is 404 (source_not_indexed) and a malformed path is 400 (nw-682)Handle the machine-readable error code; an arbitrary file path is no longer read from disk
An ambiguous /source path is 409 (ambiguous_file, with repo candidates), and the web UI lets you choose a repo (nw-683)Pass repo=<repo uid> when a relative path exists in more than one indexed repo
Web UI: a deep link with scene params (node, mode, lens, seeds, kind, workspace) but no representation now opens the graph representation; it used to keep the JSON/table mode left in browser storage and write it back into the URL (nw-571)Add representation=table (or json, matrix) to a link that needs a non-graph view
Web UI: ?kind=repo (or note, service, symbol) without a node now filters Overview to that landmark kind and stays in the URL; it used to be stripped to / and ignored. Any other kind without a node shows a warning. GET /api/v1/overview accepts `kind=reposervice
Web UI: ?engine=wasm now stays in the URL (it used to be stripped on the first state change, which quietly returned the page to the server engine), downloads snapshot.msgpack once per graph generation instead of four times, and the status bar shows the active engine (nw-570)Nothing to change; drop engine=wasm from a link to return to the server engine
An unreadable, invalid UTF-8 or invalid-glob .brainignore now refuses vault add, refresh and watch before changing indexed notes or sidecars (nw-684)Repair the file and retry; a missing .brainignore still means no extra exclusions
Note-to-code links now scope candidate definitions before preferring them (nw-685)Expect links into the note's own project when another project defines the same name
A new note under a project's vault_folder gains project membership during reconciliation (nw-679)Expect newly created notes in project-context after reconciliation
A UID seed with no text label no longer opens a semantic seed search (nw-686)Expect structural results for the UID without unrelated semantic matches
read-symbols verifies indexed spans and reports stale or relocated source instead of returning another symbol's body (nw-689)Handle the additive stale-span/relocation fields in read-symbols responses
CommonJS module.exports.X and exports.X functions are now definitions with call edges. Resolver generation 7 requires a full repo re-index before dead-code answers (nw-687)Run nestweaver index --repo <path> --force for each repo after upgrading
A JS/TS test block is now named <runner> <title> (describe getTier, it returns gold) instead of its bare title, so it no longer shadows a real definition of the same name, and affected-tests selects the test that calls it. Only require('x') is an import (any f('x') call was one), and a call bound from an npm package (const { isEmpty } = require('lodash')) no longer gets a CROSS_REPO_LINK to another repo's same-named symbol, unless the specifier names an indexed repo's own package (its manifest name, e.g. @org/shared), which keeps an import-corroborated link. Resolver generation 8 (nw-688)Run nestweaver index --repo <path> --force for each repo after upgrading; search test blocks by the prefixed name
regex-search / MCP regex_search / count_patterns now plan a pattern from every literal a match must contain, not only its prefix, so fn\s+run_\w+_reconciler uses the trigram index instead of a full scan that could time out empty. Case-insensitive patterns, small classes, ? and alternations plan too. Results are unchanged; scanned_fallback is false for more patterns (nw-697)Nothing to change; expect fewer scanned_fallback answers and fewer deadline-empty results
Server mode: a code re-index no longer drops note-to-code links until the next vault fetch. After each code fetch the index worker records the debt (brain status shows Note→code links: being rebuilt (code re-index of <url>) and code_links.pending), then one debounced relink task (bursts coalesce; it stops on shutdown) relinks from the vaults' bare clones and clears it. A direct (--no-daemon) code watch still only records the debt; the daemon's first pass settles it (nw-677)Gate on code_links.pending as before; expect it briefly after each server-side code fetch
The daemon's manifest rebuild is now per repo: a repo it must refuse (source eligibility recorded under other settings, a missing root, a malformed manifest, the shared 32 MiB budget) no longer keeps every repo's manifests stale. The others are published and manifest-debt.json is cleared; each refused repo is logged and recorded inside the manifest sidecar's own envelope (so it is published, generation-bound and backed up with the manifests), re-probed alone with backoff (30 s doubling to 30 min), and named with its reason and a remedy that fits the case (nestweaver index --repo <path>; restore or nestweaver remove-repo <uid> for a missing root; re-fetch for a server-mode repo) in brain status (a Manifests not current for N repo(s) block; additive JSON manifest_failures[] with repo_uid, repo_url, root, reason, remedy), in suggest-links (text note; additive JSON manifest_failures), and in the dead-code manifest disclosure. A capture that exceeds its own per-repo 60 s budget (started after the write gate is held) refuses no repo: the snapshot is deferred as contention and retried, and brain status JSON carries the runtime state as manifest_recovery (state, attempts, retry_after_seconds, error), with a manifest_recovery warning while it is deferred, retry_scheduled or blocked. This supersedes the old "malformed manifest → 503" contract: suggest-links (HTTP and CLI) now answers 200 from the repos that are current and names the refused repo, instead of refusing the whole answer (nw-705)Run the named remedy for each refused repo
In unscoped investigate, an exact symbol name remains a seed while longer substring matches are connected results; partial matches remain seeds when there is no exact match (nw-529)Treat is_seed as the query match indicator; results still include relevant connected symbols
Invalid export --format / --scope now exits 64, not 1Gate on 64 for usage errors; 1 still means the export itself failed
A value a tool's schema rejects (e.g. an over-long read-symbols target) now exits 64, not 1, on the daemon route, and on the --no-daemon route for commands that run through the shared tool layer (brain search, project-context, clusters, blast-radius, …). Direct-route commands that call the engine without the tool layer (e.g. read-symbols --no-daemon) never see the schema and keep their own exit codesGate on 64 for usage errors; 1 still means the command itself failed
index --repo … --fail-on-skip now exits 1 when a subdirectory cannot be read (it used to exit 0 with coverage_status: "complete" and that directory's files silently missing). The directory is a read_error row in skipped_files and coverage_status is "degraded"; indexing still completes, and files already indexed under it are kept. An ignore file (.gitignore, .ignore) with a pattern that cannot be parsed is also disclosed now, as an ignored row naming the fileFix the directory's permissions (or exclude it) and re-run; drop --fail-on-skip if a partial index is acceptable
brain add, brain refresh without --since (daemon route) and MCP brain_add_source used to end in [Error] — exit 1, or an MCP tool error — on ANY vault coverage gap, e.g. one note that fails to parse or an unreadable subdirectory. They now finish Done: exit 0, MCP status: "indexed" with coverage_status: "degraded", and a message saying the vault was "NOT marked current" (its derivation is recorded Blocked and counted by brain status)Gate on coverage_status (MCP) or the skipped-file list, not the exit code, to detect a partial vault index
index on a repo holding a binary file with a contract-language extension (.ts/.js/.java/.kt — an MPEG transport stream is .ts) used to fail with prepare incremental contract derivation / prepare strict contract derivation and record contract_derivation_failed. It now succeeds and discloses the file as ONE binary row in skipped_files (coverage_status: "degraded", so --fail-on-skip exits 1). The live code watcher likewise stops skipping every batch over it, and no longer fails a batch over an unreadable file in a language that cannot contribute a contractNothing to change unless a script relied on the failure; gate on skipped_files / coverage_status
Registering a vault under a name another vault at a different root already holds is now refused — compared ignoring case, so Brain beside brain is refused too. This covers brain add, brain refresh (with or without --since), brain watch and MCP brain_add_source; the error names the existing vault's root and the brain remove … --instance … step. A vault already in the graph still refreshes in placePass a distinct --name for the second vault, or remove the old one first if the vault moved
brain status now reads Watcher reconciliation pending: N file(s) (was note(s)), and the count includes source files the code watcher owes as well as vault notesMatch on file(s), or read skipped_notes.reconciliation_pending from --json
Notes whose YAML frontmatter cannot be parsed are still indexed, but are now disclosed under one label, Notes indexed without frontmatter (unparsable YAML): N, in the brain add / brain refresh output and in brain status. As JSON, brain status --json and MCP brain_status gain skipped_notes.frontmatter_unparsed (count) and frontmatter_unparsed_notes ({path, reason} rows), MCP brain_add_source gains the same two fields, and daemon progress gains IndexProgress.frontmatter_unparsed. All additive; these notes do NOT count toward skipped_count or coverage_status, since they were indexedFix the YAML to restore those notes' tags and properties; nothing to change in scripts
A vlt: or repo: UID given as a context seed (brain context, MCP brain_context) used to exit 0 with nothing connected. It now expands to the vault's notes or the repo's symbols; the most central few stay seeds and the cut is disclosed through seeds_truncated / seed_matches_total. A vlt: seed for a vault with no notes is its own Seed container is empty error (see the empty-vault row)Expect results (and a non-empty seeds_truncated) for container seeds; handle the error for an empty vault
Web API GET /api/v1/brain/notes now honours ?vault= (alias vault_uid; an unknown vault is 404, it used to be ignored), sends the filter's total in X-Total-Count, pages by uid cursor with ?after= (the next cursor is in X-Next-After, form-urlencoded, absent at the end — a page can be short mid-vault when corrupt rows are dropped), and rejects after with offset as 400. An offset past 1000 now returns an empty page instead of repeating rows 1000..Page with after + X-Next-After instead of offset; the body is still a plain array
The brain watcher now discloses notes whose text landed but whose code links failed to write, as brain watcher code links not yet written; retrying rows under Watcher reconciliation pending, and replays them after a restartNothing to change; the rows clear once the links are written
A full brain refresh (and brain add through the daemon) no longer leaves every note without its code links, and a code re-index no longer leaves notes without their links into the changed files: the daemon's code-link reconciler rebuilds exactly the notes whose links no longer match their text, in the background. While links are owed, brain status prints a Note→code links: being rebuilt (…) line (with progress and the last error if a pass failed), brain status --json / MCP brain_status / the daemon status RPC gain an additive code_links object (pending, reason, since, progress, last_error, failures, rules_version, current_rules_version, last_reconciled_at), and brain_context, project_context and investigate answers carry code_links_incomplete: true plus code_links_pending; all clear when a pass landsGate on code_links.pending or code_links_incomplete; expect them briefly after a refresh or re-index
Name-inferred cross-repo call links (CROSS_REPO_LINK edges with cross_repo_name_* evidence) no longer depend on the order repositories were indexed in, and re-indexing a repository (or a code watcher batch in it) no longer drops the links other repositories had into it. nestweaver index (direct and through the daemon) now ends every run, including one that changed nothing, with one whole-graph inference that replaces those links (it writes only when they differ, and heals a brain indexed before this change on its next index). Code watcher batches (daemon or direct watch) and server-mode fetches record the debt; one debounced background pass (a 3 s quiet period, at most 60 s) pays it, and a daemon also runs one pass at startup. While it is owed, brain status prints Cross-repo links: being re-inferred (…) (with the last error if a pass refused), and brain status --json / MCP brain_status / the daemon status RPC gain an additive cross_repo_links object (pending, reason, since, last_error, failures, last_reconciled_at). A pass that cannot read an indexed file (not in the parse cache, and its content changed on disk) refuses and leaves the stored links alone. The parse cache gains an append-only log beside it, <db>.parsed_cache.log, folded into <db>.parsed_cache.bin by the next full indexGate cross-repo impact, blast-radius and affected-tests answers on cross_repo_links.pending; re-index a repository named in last_error
Note-to-code links (REFERENCES_CODE) now follow explicit code mentions and project scope: a name links when written as code (a backtick span, a code block, or an identifier-shaped snake_case/camelCase name or a call( in prose) and it resolves within the note's project to at most 5 defining files; plain English words, URLs, wikilinks and string literals never link, and main is stoplisted. Offline on a real brain this is ~700× fewer links (39 M → ~56 K) at ~97 % precision. First start after upgrading (local daemon): the daemon's code-link reconciler removes every old link in one step (the two link tables are dropped and recreated in one transaction and one publication — 0.11 s for 1,000,000 edges in a fixture; ranked reads fail closed only for that window) and then relinks note by note in the background, 100 notes per write. Until it finishes, brain status reports the pending relink and ranked reads carry a disclosure that note→code links are incomplete. The relink time on a large brain has not been measured; it is bounded by reading every note once. An interrupted migration starts over on the next start. Server mode has no reconciler: a vault's notes are relinked under the new rules when the worker next fetches that vault, and a code re-index there does not relink notesTo keep a link for a plain name, write it as code (`Processor`, review()) or put the note in the project whose repo defines it
Project code membership is now a durable Project→Repo edge (PROJECT_INCLUDES_REPO), so re-indexing no longer empties project_context of code (nw-678). The local daemon rebuilds this membership from its config before each code-link pass, so no manual step is needed after upgrading. materialize-projects stops writing the per-symbol PROJECT_INCLUDES_SYMBOL edges and clears each project's old ones; until then, legacy edges are read alongside the new membership, so a project→symbol pair can be counted twice in ranking. The ranking graph's definition changed, so the first ranked query after upgrading recomputes PageRank once. Downgrade: once the new materialize-projects has cleared the legacy edges, an older binary sees no project code; upgrading again restores it through the daemon's startup rebuild. project_context reports code_membership_gap for a project that declares repos but has no member repoNothing to change; to downgrade, re-run the old binary's materialize-projects
impact --no-daemon now caps at 50 like the daemon route; --limit maxes at 1000Pass --limit explicitly if you relied on an uncapped direct route
project-context without --include-components now includes component sub-projectsPass --include-components false to keep the old behaviour
_meta moved from the MCP envelope into the payload and lost its nestweaver.io/ prefixRaw HTTP MCP clients must read payload._meta, not envelope["nestweaver.io/sources"]
hubs --json / bridges --json are objects, not bare arraysRead .hubs / .bridges, not .[0]
NESTWEAVER_NO_DAEMON alone no longer permits a daemon bypassStandard artifacts always use the daemon; even the unpublished CI artifact requires a GitHub Actions runner context, not a local CI=true

Server Mode

NestWeaver can run as a centralized server, indexing repos for your entire team and serving queries to AI agents via gRPC and MCP-over-HTTP.

Quick Start

# Start the server (TLS required for grpcs:// clients)
nestweaver daemon --db ./brain.lbug run \
  --server \
  --bind 0.0.0.0:9378 \
  --tls-cert ./tls/server.pem \
  --tls-key ./tls/server-key.pem \
  --auth-token "$NESTWEAVER_AUTH_TOKEN"

# Connect from another machine
nestweaver connect grpcs://nestweaver.internal:9378 --token "$NESTWEAVER_AUTH_TOKEN"

Ports

PortProtocolPurpose
3000HTTPWeb UI (optional, nestweaver ui; 9377 in the macOS .app)
9378gRPCQuery API (TCP + TLS)
9379HTTPMCP-over-HTTP (AI agents) + /webhook + /admin/api/* + Prometheus /metrics

In server mode the daemon serves Prometheus /metrics on the MCP HTTP port (9379) — gRPC port + 1, inheriting the --bind IP. nestweaver ui serves the same route on its own listen port (default 3000). The macOS app serves the UI, including /metrics, on 9377.

Docker

docker compose up -d

See Server Mode Guide for full documentation.

Install

macOS app (source build)

The native NestWeaver.app is source-build-only until a release job publishes a .app bundle or DMG. Build it from source (it bundles Metal-accelerated embeddings and the web UI):

bash app/build.sh
open target/release/NestWeaver.app

For a frozen candidate, retain the CLI and workspace test executables from one Cargo compilation, then run those exact executables without rebuilding:

bash app/build.sh --validation-artifacts /tmp/nestweaver-validation
python3 scripts/test-validation-artifacts.py --manifest /tmp/nestweaver-validation/artifacts.json

The validation mode uses the normal release/Metal profile and app packaging. It checks that the packaged CLI matches the artifact manifest. The affected Mac must validate the source build and app launch; Linux cannot establish those results. For Linux, build the frontend first, then use python3 scripts/build-validation-artifacts.py --output /tmp/nestweaver-validation. Both artifact commands require a clean, committed source tree. Test exclusions must be explicit and are recorded in the results; legacy direct-mode integration fixtures require the separate CI-only artifact/runner and cannot run locally.

The .app bundle gives you a menubar status icon, Metal GPU acceleration (~5x faster embeddings via a launchd-managed daemon), a persistent daemon shared with the CLI/MCP, web UI on port 9377, and launchd-managed restart. See macOS App below.

Supported platforms (CLI)

Install the release-matched CLI wrapper from npm:

npm install --global nestweaver
nestweaver --version

Alternatively, select the GitHub Release archive for your platform, verify its matching SHA-256 file, then install it as described in INSTALL.md. Both macOS CLI archives are built with Metal support. The default accelerator = "auto" therefore requires Metal in those builds and reports a Metal initialization or inference-probe failure instead of retrying on CPU. To opt out explicitly, set accelerator = "cpu" in the [embedding] section of your instance configuration. Builds without Metal support select CPU for auto.

PlatformRelease target
Linux x86_64x86_64-unknown-linux-gnu
Linux aarch64aarch64-unknown-linux-gnu
macOS Intelx86_64-apple-darwin
macOS Apple Siliconaarch64-apple-darwin
# After cloning the source repository (current stable Rust)
eval "$(scripts/fetch-lbug-source.sh)"
cargo install --locked --path .

Source builds also require CMake, a C++20 compiler, Python 3.9+, OpenSSL and zstd development files, pkg-config, and Protocol Buffers. The checkout builds LadybugDB from source rather than downloading a prebuilt archive; keep .cargo/config.toml intact. See the source-build prerequisites before building.

Pre-built binaries

Download a pre-built CLI archive and its matching .sha256 file from GitHub Releases. Binaries are available for Linux and macOS on both x86_64 and aarch64; use the target table above and follow the checksum verification in INSTALL.md.

Build from source
git clone https://github.com/Kehl-io/nestweaver.git
cd nestweaver
eval "$(scripts/fetch-lbug-source.sh)"
cargo install --locked --path .
# On macOS with Metal embeddings:
# cargo install --locked --path . --features metal

The first build compiles LadybugDB from source and may take several minutes.

CLI Reference

Core Commands
CommandDescription
indexParse and index a repository (auto-detects repo root from .git). Use --name to set a custom repo name for multi-repo setups. Indexing does NOT refresh trigrams implicitly — the daemon's reconcile loop owns that (see [indexing] trigram_reconcile_interval). --with-trigrams forces an inline refresh for one run (CI, scripted reindex), --no-trigrams suppresses it (and conflicts with --rebuild-trigrams), --rebuild-trigrams forces a full rebuild. A direct index (no daemon) refreshes trigrams only with --with-trigrams, --rebuild-trigrams, or [indexing] with_trigrams = true.
watchLive re-indexing via filesystem watcher with debouncing. Runs daemon-side (no instance config required; unsafe roots are denylisted); --force replaces an existing watcher. Incremental reindex preserves CALLS/IMPORTS edges (reverse dependents are re-resolved) and reports per-file failures instead of dying
watch-stopStop the daemon's active watcher. The watcher slot is global and the daemon keeps no liveness check on the CLI that registered it, so a watch killed without a clean shutdown (SIGKILL, or a closed terminal) leaves the slot occupied and every later watch refused; this releases it without restarting the daemon
contextGet task-focused context via PPR (supports --intent for tuned retrieval)
searchSymbol-name substring lookup. Notes and BM25 full-text search are brain search
symbolLook up a symbol by name and display its metadata
impactTrace the blast radius of a symbol through the dependency graph (fails closed on unknown/foreign UIDs, exit 2; --depth 1–15; --limit 1–1000, default 50 on both routes — --no-daemon used to be uncapped and now matches the daemon, so a symbol with more than 1000 depth-1 dependents has rows unreachable at any limit; pruning by impact-score threshold or depth is disclosed, --min-score 0 opts out)
blast-radiusAssess blast radius for a set of changed files; reports gate_state/status and blind spots, and never reports ok for a truncated traversal
detect-changesRun the MCP-compatible changed-file impact contract directly from the CLI, including risk, gate state, status, and blind spots
flow-traceTrace forward execution flow from a symbol — what it calls, and what those call
read-symbolsRead a symbol's source span. Omitting --root reads each symbol from its recorded repo working tree; --root still pins a single filesystem root
regex-searchRegex search over indexed text (scope-aware trigram pre-filter; safely scans only missing or stale scopes with stale_index: true — refresh now with index --with-trigrams, or set [indexing] with_trigrams = true so the daemon's reconcile loop keeps the pre-filter fresh on trigram_reconcile_interval)
count-patternsCount regex matches per pattern (--max-millis budget; exits 75 when it cuts a count)
investigateOrient on a topic in one call
investigate-expandDrill into investigate bundle entries — full body plus immediate neighbours
investigate-hydrateFill in bodies/summaries for all un-hydrated entries of a bundle
affected-testsSelect tests for changed files in one repository (tiered; carries a recommendation CI directive — run-full-suite on any degraded run or when changed files have unrecognized extensions like Makefile/CI YAML/.sql). --repo <name or UID> names the repository; it is required with --files when several repos are indexed (exit 64 otherwise). --base-ref diffs against the working tree, not the merge-base
repo-mapGenerate a token-budgeted map of the repository structure
summaryHierarchical code summaries at symbol, file, or cluster level
Brain Commands
CommandDescription
brain addAdd an Obsidian vault or markdown directory to the knowledge graph
brain searchSearch across code symbols, notes, headings, sections, and tags (--limit 1–1000)
brain contextGet unified context spanning both code symbols and notes (skips the semantic leg entirely when the DB has no embeddings; identical concurrent calls coalesce single-flight)
brain listList all registered vaults
brain statusShow vault counts, per-vault staleness, and index health
brain watchWatch vaults for changes and re-index automatically. --force adopts an existing watcher registration instead of being refused by it — the vault counterpart of watch --force
brain refreshForce a full re-index of one vault directory (nestweaver brain refresh <path>)
brain removeRemove a vault from the brain (cascade-deletes nodes; does not touch files on disk)
brain stale-checkCheck whether the indexed graph reflects reality (also available top-level as stale-check). Exit 0 nothing to do · 1 the check itself failed · 2 at least one repo needs re-indexing. Gate CI on any_needs_reindex (or exit 2) — that is the actionable union of stale, incomplete, and missing. A repo that indexed successfully with zero eligible source files is no_indexable_content (human: empty) and does not pin exit 2. any_stale / is_stale mean behind HEAD specifically
brain diff <repo>Show what changed in the graph since a commit (--since-sha <sha>, --limit 1–1000 default 50, --json, --db, --config). Local repos only; the CLI twin of the MCP brain_diff tool
brain reindex-searchRebuild the Tantivy BM25 search index from current graph state
brain broken-linksList unresolved and ambiguous wikilinks, with suggested fixes. low_confidence is a separate list of links that did resolve and is not counted in total
brain orphansList notes with zero inbound and zero outbound wikilinks
brain topic-clustersDetect topic clusters via Louvain-style local-moving community detection over note wikilinks
brain tag-graphShow a tag's note count and co-occurring tags (or dump the full tag graph)
brain doc-statsOne-shot health summary: note/wikilink counts, broken links, orphans, top tags
backlinksResolve a note by UID or title and list the notes that link to it
note get <target>Read one note by note: UID or by title (--json, --db, --config). Read-only; the CLI twin of the MCP note_get tool. Exits 2 when the title or UID resolves to nothing
memory lintHealth checks over the vault (stale notes, broken links, orphans). --limit 1–1000 (default 50) caps each category; *_total is always reported, and the human summary prints N of M when a category is truncated
memory consolidatePropose/apply tier promotions (logs → ideas → project files). --limit 1–1000 (default 50) caps returned proposals; human output discloses proposals_total when truncated
memory relatedTyped-edge traversal from a note (supersedes, depends-on, etc.). --limit 1–1000 (default 50) with returned/total/truncated; human output prints N of M when truncated
Publication Commands
CommandDescription
publication rebuild --config <path>Build a fresh graph and every derived artifact beside the incumbent, validate it, then atomically activate it
publication statusInspect resumable operations and report corrupt/incompatible journals independently
publication cancelRequest cooperative cancellation at an exact observed journal revision
publication discardRemove failed staging at an exact revision, or safely discard only an invalid journal
publication rollbackSwitch back one step to the retained predecessor while the daemon is stopped
repairReconcile an index publication abandoned by a crashed indexer. While <db>.index-dirty exists for a full index publication — or a watcher marker is wedged — every ranked query fails closed; this removes the stale PageRank sidecar, advances the generation, clears the marker and recomputes. Refuses a marker it cannot prove abandoned unless --force, and never overrides a live writer
publication pruneReclaim slots nothing can still reach. Keeps the slot CURRENT selects, its retained predecessor (the one-step rollback target), and any slot an in-flight operation targets; --dry-run previews. Takes the publication-root lock, so it serializes against rebuild/rollback/discard

The regex-v3/embedding-v2 upgrade requires this one-time full rebuild. See the publication rebuild and recovery guide.

Ranked reads during a publication. Not every publication fails a ranked read closed any more. A brain watcher batch publication now lets ranked reads succeed, returning results plus a disclosure of what was in flight. A full index publication still fails closed, and so does a wedged watcher marker — those two are unchanged. MCP responses computed during a live publication carry four disclosure keys:

KeyMeaning
publication_in_progressa publication was in flight while this answer was computed
marker_age_sage of the publication marker, in seconds
in_flight_note_pathsthe note paths being published, capped at 20
in_flight_note_paths_truncatedtrue when more than 20 paths were in flight

Known gap: CLI --json verbs that reshape the response into a typed struct — nestweaver hubs --json among them — drop these keys. Their absence from a CLI JSON payload is therefore not evidence that no publication was running.

Analysis Commands
CommandDescription
hubsFind most connected hub nodes (degree centrality + PageRank)
bridgesFind architectural chokepoints (betweenness centrality)
pr-impactPR blast radius analysis with risk scoring (Low/Medium/High, or Unknown when a changed file could not be assessed); --sarif for code scanning, --strict to gate on contract-verified breaking changes
rts-eval record-truthReport a full-suite outcome from CI so selection quality can be measured
rts-eval reportMeasured file-recall / change-recall / selection-breadth of past selections (refuses percentages below 10 joined runs)
dead-codeA review aid, not a deletion list, and it refuses to produce one at all on a resolver-generation-stale graph — exit 2, refused: true with reason: "outdated_resolver" and a runnable remedies[].command on --json, on every route including MCP. A missing edge can only fail to reach a live symbol, so an under-resolved graph moves live code onto a deletion list; re-index with nestweaver index --repo <path> --force and re-run. Detects symbols no entry point reaches, which is not the same as "nothing references it" — a reference the parser does not capture is indistinguishable from no reference at all. Measured top-15 precision on Rust was 0/15, and it remains poor on C++; treat every confidence tier as review candidates, never as proof. unreachable_count is the unfiltered total; matching_count reflects --min-confidence; --limit is 1–1000, default 50 (there is no "all"); coverage: "degraded" means the walk proved nothing — no entry point or module owner root (entry_points + module_owner_roots == 0), undecodable symbols in the store, or a language that contributed analysed symbols but zero entry points of its own (named in languages_without_entry_points) — so every row below is unreachable by construction. Rust pub mod Modules are never flagged. A Rust impl block is reachable when ANY of its members is, and a dead one now suppresses its own Method members instead of listing the block and every method separately (associated Constants still surface). Rows are deterministically ordered with a uid tie-break, so which of them survive --limit no longer varies run to run
rerankLightweight result reranker (off-by-default heuristic)
infoShow hardware and configuration information
contracts listList API contracts derived from spec files + framework handlers
contracts driftRoutes declared in a spec but not implemented, and vice versa (presence-level)
contracts diffField/type-level OpenAPI breaking-change diff between two spec versions (--base/--head, --fail-on-breaking for CI)
rankingInspect ranking priors
evalOffline retrieval-quality evaluation
exportExport the graph in Cypher, GraphML, Mermaid, or MessagePack format (cypher/graphml/mermaid carry real PageRank scores; mermaid --top N ranks by PageRank; msgpack always writes to --output/<db>.graph.msgpack, never stdout). An invalid --format or --scope value now exits 64 (EX_USAGE), not 1 — an unsupported but valid combination, such as --format cypher --scope vault, still exits 1

What counts as an entry point. Reachability is a forward walk from entry points, so what the parser accepts as one decides what dead-code reads as dead:

  • bash — trap handlers are entry points, including quoted flags and traps nested inside functions. Any command with no enclosing function also roots its same-file callee, so a script with a bare top level now has entry points at all; it used to have none, and every function in such a script read as 100% dead. Trap handler resolution is SAME-FILE ONLY — a handler defined in a sourced file (source lib.sh; trap cleanup EXIT) is not resolved and shows as unreachable.
  • Swift — a top-level call in main.swift, or in a shebang-led file, roots its callee. Known gap: swiftc foo.swift on a file that is neither main.swift nor shebang-led is missed.
  • Python — a module-scope call roots a same-file function, which covers if __name__ == "__main__": with no special case for it. Restricted to bare identifiers (obj.run() roots nothing) and to functions, never methods.
  • module_init (JS/TS/Python/PHP) — calls a file makes at its top level, outside any function, class or method, are owned by a per-file <module> symbol, so the functions they call are live and show a caller in impact. That covers bare calls, IIFEs, Express-style handlers registered at load, decorators and __main__ guards, and works across files (the owner calls an imported function). require(...) alone does not create an owner. An owner that calls something is also its own <repo-relative path>::<module> process, so the process list grows for files with decorators, route registration or top-level test setup. The owner is excluded from dead-code output and counted in module_owner_roots, not entry_points.
  • C++ — an error-recovered, macro-prefixed declaration is re-anchored to its name's line, which CHANGES that symbol's UID. A local whose type is an inline anonymous struct or class is reclassified Function → Variable (the most-vexing-parse fix).
  • Manifests — package.json entry points are discovered at ANY depth, so a monorepo's packages/*/package.json counts. Paths are rebased against the manifest's own directory, and the browser field is now an entry file.
Multi-Repo and Projects
CommandDescription
list-projectsList all projects defined in the instance config
project-contextGet context scoped to a specific project. --include-components is now three-state: omitting it means true, which is the documented default the schema always declared — pass --include-components false to exclude component sub-projects. Before 9.0.0 the CLI sent an unconditional false, so the documented default was unreachable on this route. The MCP kinds filter, when it is only Symbol, does not seed or promote member notes into the walk
materialize-projectsMaterialize declared projects, wiki sources, and cross-repo links from instance config
detect-implicit-projectsDetect implicit projects from vault structure and code patterns
suggest-linksDiscover potential cross-repo links between symbols
list-linksList all cross-repo links in the instance
list-featuresList features spanning multiple repositories
clustersDetect community clusters in the dependency graph (Louvain-style local moving, single-level; results cached in a sidecar, cluster <id|name> reads the cache)
cross-repo-contractsRun the MCP-compatible cross-repository contract query for a symbol name or UID
cross-repo-refsSame JSON envelope as cross-repo-contracts / the cross_repo_contracts MCP tool (including link_type: "contract" rows). --limit 1–1000 (default 50). --repo only disambiguates an ambiguous symbol name before that query; it is not the contracts row filter. Without --repo, an ambiguous name uses the same preferred match as cross-repo-contracts
Server and Admin
CommandDescription
mcpStart the MCP server (43 tools; 36 in direct read-only mode; 6 with --lite; auto-starts daemon)
daemonManage the background daemon (start, stop, status, restart, gc; run --server for server mode). daemon status exits 69 when the daemon is running but unhealthy
connectConnect to an upstream NestWeaver server (federated read/impact)
serverServer management utilities (init-tls, backup, status)
uiLaunch the interactive web UI
setupAuto-detect and configure AI tools (16 supported). Use --force to regenerate customized files
generate-guideGenerate tool-specific instruction files (skill, cursor-rule, agents-md, claude-md)
completionsGenerate shell completions (bash, zsh, fish, powershell)
embedGenerate vector embeddings for symbols, notes, and headings using a local model (Metal-accelerated) or external API. Reports an eligibility plan before embedding and exits successfully without loading the model when nothing is eligible; --force re-embeds everything
pullPull repository source into a local workspace (sparse checkout by default; --full, --pinned, --ephemeral)
config validateValidate an instance config without creating files or contacting services (--json for a machine-readable result)
diagnostics capabilitiesReport embedding and Metal compile/runtime capabilities, including whether Metal was selected or fell back (--json)
instanceManage instance configuration. abort-migration clears a wedged migration journal so the daemon can boot
snapshotManage graph snapshots (build, verify, push)
backupBackup and restore the NestWeaver database
list-reposList all indexed repositories
remove-repoRemove an indexed repository and all its data (symbols, files, services, contracts) from the graph
remove-projectRemove a materialized project and its edges from the graph
prune-staleRemove repos and vaults whose source directories no longer exist on disk
compact-embeddingsReclaim embedding vectors left behind by deleted nodes (--dry-run, --json); no model load
list-servicesList all detected services
service-summaryDisplay a summary of a specific service
adminSubagent guidance instructions
interactionsManage interaction memory (status, show, clear, and forget <uid> to drop one node's memory while leaving the rest intact)
extensionsRead back the annotations agents write via the set_extension MCP tool (list, and unset to remove one property from one node)
hooksInstall/remove the local pre-push blast-radius check (--install, --strict, --uninstall, --db)
pre-push-impactAnalyse local changes against the org-wide graph (alias ppi). The hooks pre-push check runs pr-impact, not this command
format-commentFormat impact analysis results as a PR/MR comment, for CI to post

Local pre-push check

Get "confidence before you push" from the same hardened blast-radius analysis CI runs — locally, on your machine:

nestweaver hooks --install --db "$(pwd)/nestweaver.lbug"

This writes a .git/hooks/pre-push that runs nestweaver pr-impact against the merge-base before every push. It is advisory by default: it never blocks your push (fail-open), stays silent on a trivial change, and prints a concise banner — the gate verdict, the top affected symbols, and a coverage caveat when the analysis was incomplete — only when there's something to review. A degraded/incomplete run never blocks, because an incomplete traversal can't be trusted to have found the risk.

To make it block a push (exit 2) on a contract-verified breaking change — a decidable API-signature break, not a heuristic:

nestweaver hooks --install --strict

What --strict blocks on is configurable via the [pr_impact] section of nestweaver-instance.toml (strict_block_on_breaking, default true; strict_block_on_high_risk, default false — opt in to also block on a complete High-risk run). A degraded/incomplete run is never blocked on risk.

Remove it (restoring any hook it backed up) with:

nestweaver hooks --uninstall

You can also run the check manually — this is exactly what the hook does:

nestweaver pr-impact --base origin/main            # advisory banner
nestweaver pr-impact --base origin/main --strict   # exit 2 on a contract-verified breaking change (default policy)

Features

Markdown Brain

Index Obsidian vaults and markdown directories alongside your code. NestWeaver builds a unified knowledge graph that connects notes, sections, and tags to code symbols — letting you query across both worlds. Wiki/HTML content is auto-converted to markdown during ingestion. Use .brainignore for glob exclusion patterns or --ignore for ad-hoc filtering.

# Add a vault to the knowledge graph
nestweaver brain add ~/Documents/Obsidian/MyVault

# Search across code symbols and vault notes
nestweaver brain search "architecture"

# Get unified context spanning code and notes
nestweaver brain context "MyProject"
Semantic Search (Embedding Seed Layer)

NestWeaver embeds symbols, notes, and headings using the configured local or external backend, then uses semantic similarity as one of the signals ranking the graph walk. Backend and device selection are explicit: failures are reported and never switch to another backend or device.

# Embed all indexed content (one-time, incremental after)
nestweaver embed --stats

# Ask a question in plain language
nestweaver investigate "how does the daemon decide when to reindex a repository"
nestweaver investigate "where does the upload pipeline start"

Use investigate for a question; use context/brain context for a name you already know. This is the one distinction worth learning up front. context and brain context RESOLVE their argument to seed nodes — as a UID, note title, tag, symbol name, or a qualified name such as path::name, path::<module> or Class::method — and a multi-word question resolves to none of those, so they exit 2 with No seeds resolved even on a fully embedded graph with a daemon running (under --json, the not-found envelope's message carries that text, including the investigate command to run instead). investigate is the natural-language entry point: when seed resolution finds nothing it falls back to BM25 over the corpus, so a question still returns an answer.

Three retrieval signals are fused via Convex Combination: PPR (graph structure), BM25 (text match), and semantic (embedding similarity). Semantic similarity re-ranks and blends candidates; it is not, on its own, a natural-language front door for the seed-resolving commands.

Device policy.

acceleratorLocal-backend behavior
autoMetal in a Metal-enabled build; CPU only when Metal is not compiled. A Metal failure is reported; auto does not retry on CPU.
metalRequires Metal to be compiled and the device plus full model inference probe to succeed; otherwise embedding state is failed.
cpuSelects CPU directly and never probes Metal.

Model selection and cache. The default is the light, fast sentence-transformers/all-MiniLM-L6-v2 (384-dim, ~90MB) — a good fit for most repos and CPU-only servers. NestWeaver records the model used for each database, and the daemon loads that recorded model to avoid dimension mismatches. Daemon startup is cache-only: it never downloads model files or contacts Hugging Face. The configured cache_dir expands a leading ~/ against the daemon user's home directory.

A missing model cache repairs itself. If the recorded model is absent from the cache, nestweaver embed recovers it in one call — no daemon stop, no restart. It downloads the missing artifacts, loads them, prints one line ahead of the normal summary, and exits 0:

nestweaver embed --db /absolute/path/to/brain.lbug
# Downloaded missing embedding model '<id>' into <cache-dir> and loaded it (device: <device>).

The daemon repairs itself too, in a bounded background seed. When a boot load fails because the artifacts are missing, the backend is local, and the database already carries a verified embedding identity naming that model, the daemon downloads it in the background after the socket is bound — so boot stays cache-only and the download never delays it. It is never a first-time download: with no recorded identity there is nothing to repair and nothing is fetched. At most 5 attempts, backing off 30s / 2m / 8m / 30m (each jittered ±20%), stopping early on a permanent error (404, 401, 403, permission denied, ENOSPC). Opt out with [embedding] auto_repair_cache = false — it defaults to true.

brain status grows a Download: line while a seed is running, naming who asked for it and which attempt is in flight:

Download:  <done> of <total> (automatic repair, attempt N of M)
Download:  <done> of <total> (requested by nestweaver embed)
Download:  retry N of M in <duration>

While a seed is active the embedding state is "seeding". It takes precedence over every other state, ready included, and reports degraded_components: ["semantic"].

External embedding endpoints. Instead of a local model you can embed via an OpenAI-compatible endpoint: nestweaver embed --endpoint http://localhost:11434 --model nomic-embed-text (Ollama), or a hosted gateway. For keyed gateways (OpenAI, Azure), set NESTWEAVER_EMBED_API_KEY — it is sent as a bearer token and is never written to config, the graph, or a snapshot. An external endpoint is authoritative: a load or request failure is reported and does not load a local model. Switching backends requires both an explicit configuration change and re-embedding: remove external_endpoint, stop the daemon, and replace the recorded external model metadata/vectors with the chosen local model.

The stop/start recipe below is for an intentional model SWITCH only — it is the one case that still needs one. It is not the repair for a missing cache: that is a single nestweaver embed call with the daemon left running, described above. --force appears here because you are deliberately discarding the recorded model and its vectors, never because a download is missing:

CONFIG=/absolute/path/to/nestweaver-instance.toml
DB=/absolute/path/to/brain.lbug
MODEL=sentence-transformers/all-MiniLM-L6-v2
CACHE="$HOME/.cache/nestweaver/models"
nestweaver daemon --db "$DB" stop
nestweaver embed --db "$DB" --local --model-id "$MODEL" --cache-dir "$CACHE" --force
nestweaver daemon --db "$DB" start --config "$CONFIG"

NestWeaver records the index dimension and rejects mismatched vectors, so any model/backend switch requires --force. The direct path (--endpoint/--local) cannot run while a daemon holds the DB write lock; stop that daemon first or, when the configured daemon backend is already ready, drop both direct-path flags.

Stopping. nestweaver daemon stop drains in-flight writes with every listener still up, so reads keep working while it drains (individual reads can still stall for seconds while a write commits), and an idle daemon exits immediately. New writes over the gRPC surface are refused with UNAVAILABLE once shutdown starts, so the drain always finishes (the web admin routes are outside that gate — see CLAUDE.md). It never SIGKILLs on its own — if a write is still running it reports what it observed and leaves the daemon up; daemon stop --force or kill -9 end it anyway, abandoning that write. Under a process supervisor (systemd TimeoutStopSec, launchd ExitTimeOut, Docker stop_grace_period) the supervisor's own timer still applies. See the Daemon Shutdown Guide.

Readiness and diagnostics. On macOS, background start/autostart uses launchd to own a foreground daemon process; daemon run stays in the invoking foreground. Neither path forks or self-daemonizes. Readiness is published only after a real embedding inference succeeds. Inspect compile/runtime capability and the selected backend with:

nestweaver diagnostics capabilities --json
nestweaver daemon --db <path> status
nestweaver brain status --db <path> --json

The status reports requested_device, selected_device, and fallback_used. A local backend is ready only when selected_device is metal or cpu and fallback_used is false; an external backend has no local selected device. When semantic retrieval was requested but unavailable, context responses keep the graph/PPR/BM25 result and report "semantic" in degraded_components (the only value in that vocabulary today). Every path reports both fields: the direct, daemon and brain_search paths, and the hybrid/federated merges for brain_search and for brain_context / project_context. In a merge, semantic_applied is the AND across contributing tiers and degraded_components their deduplicated union; when no tier reports either field the merge omits both, so an absent field still means "not reported by any tier", never a synthesised false. Caveat: semantic_applied is one boolean, so a merge in which one tier ranked semantically and the other did not reports false — correct for the merged row set, which contains lexically ranked rows, but it does not say which tier was which.

Performance: 7ms query embedding (Metal), 37ms (CPU) for all-MiniLM; heavier models trade speed for quality. Forward Push PPR replaces power iteration for sub-10ms graph walks. LRU cache makes repeated queries instant (~8ms).

Configure the model and fusion weights in instance.toml:

[embedding]
# Shipped default; the model a DB was actually embedded with is recorded and
# auto-loaded by the daemon. Set this to override the default for fresh instances.
model_id = "sentence-transformers/all-MiniLM-L6-v2"
# cache_dir defaults to the platform-native cache directory:
# ~/Library/Caches/nestweaver/models on macOS, $XDG_CACHE_HOME/nestweaver/models
# (or ~/.cache/nestweaver/models) on Linux. Explicit values may use ~/.
# If unavailable or non-UTF-8, a UTF-8 HOME uses ~/.cache first. The final
# fallback is /var/cache/nestweaver/models on Unix or C:\ProgramData\nestweaver\models
# on Windows; set cache_dir explicitly if that system location is not writable.
# cache_dir = "~/Library/Caches/nestweaver/models"
accelerator = "auto" # auto | metal | cpu; see the policy table above
weight_ppr = 0.40
weight_bm25 = 0.25
weight_semantic = 0.35

macOS App

NestWeaver can build a native macOS .app bundle from source. No release .app bundle or DMG is currently published. A source build provides:

  • Menubar status icon with quick access to the web UI and daemon status
  • Metal GPU acceleration — the app launches the daemon as a non-forking launchd Aqua agent, then the daemon proves full model inference before reporting the Metal backend ready (~5x faster: 7ms vs 37ms).
  • Managed daemon lifecycle — launches the daemon via launchd (which owns crash-restart); the daemon is a shared service (MCP/CLI/UI all use it) and persists across app quits, so the app re-attaches to it on next launch
  • Daemon coexistence — detects if a daemon is already running (via CLI or launchd) and connects to it instead of starting a second instance
  • Web UI at http://127.0.0.1:9377 — opens automatically on launch
# Build from source (requires Xcode Command Line Tools)
bash app/build.sh
open target/release/NestWeaver.app

The app is menubar-only (no Dock icon). Click the NestWeaver icon in the menubar to open the web UI or quit. Database is auto-detected from NESTWEAVER_DB, ~/.nestweaver/instance.toml, or ~/.local/share/nestweaver/*/brain.lbug.

When to use the app vs CLI:

  • Use the app for always-on daemon with Metal GPU, menubar access, and the web UI
  • Use the CLI (nestweaver daemon start) for headless/server environments, CI, or if you prefer terminal-only workflows
Projects

Group repositories, features, and configuration into named projects using TOML config files. Projects scope queries and context to just the code that matters.

# nestweaver-instance.toml
[[projects]]
name = "payments"
repos = ["payments-api", "payments-worker"]
components = ["checkout", "refunds"]
nestweaver project-context "payments" --token-budget 5000
Multi-Repo and Instance Config

Manage multiple repositories as a single graph. NestWeaver discovers cross-repo dependencies, suggests links between related symbols, and lets you query across repository boundaries.

See the Instance Config Guide for full configuration options. If an older database mixes instance_id conventions, the Instance ID Migration Runbook consolidates it.

# Discover cross-repo links
nestweaver suggest-links --db ./all.lbug

# Get context for a feature spanning multiple repos
nestweaver context --feature device-pairing --config ./nestweaver-instance.toml --db ./all.lbug

Runtime-configurable defaults — set [limits] in your instance config to replace the builtin a command passes into resolve_limit. That builtin is not one number. Unset, search uses 10, brain search uses 20, and brain context uses 30. Commands whose builtin is DEFAULT_RESULT_LIMIT use 50. code_context is not in that set: it returns up to 500 connected symbols. brain_context is sized by token_budget (default 2000), not by a page size.

[limits]
default_result_limit = 100

CLI commands (search, brain search, brain context) also respect this setting when --limit is not explicitly passed. The [response] section controls inline body thresholds.

MCP Server

For manual installation and the proposed official registry listing, see the MCP Registry guide. Registry publication requires a separate npm release and maintainer approval.

NestWeaver exposes 43 tools via the Model Context Protocol, giving any MCP-compatible AI agent structured access to your codebase graph without reading source files directly.

Where that number comes from. The registry is all_tool_schemas_undecorated() in crates/nestweaver-mcp/src/tools.rs, and tool_doc_tests::all_tools_have_doc_categories asserts the documented tool table covers exactly tool_list(false)["tools"].len(). Do not restate the count from memory — read it back off the wire with a tools/list call, or count the registry.

nestweaver mcp --db ./nestweaver.lbug
nestweaver mcp --tools brain_context,brain_search,read_symbols --db ./nestweaver.lbug   # allowlist specific tools

# Local MCP sessions connect to the daemon; direct mode is CI-only.

Direct read-only mode advertises 36 tools — the registry minus the seven names in MUTATING_TOOLS (crates/nestweaver-mcp/src/http.rs): brain_add_source, brain_remove_source, brain_memory_consolidate, set_extension, unset_extension, prune_stale, compact_embeddings — and rejects mutations before dispatch. Daemon-backed stdio exposes all 43. --lite exposes 6. --tools names are exact, case-sensitive registry names; unknown, duplicate, empty, or transport- unavailable names fail at startup instead of silently producing an empty tool surface.

Every tool schema now carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), derived from the same MUTATING_TOOLS table, so a client can tell prune_stale from brain_status on the wire.

Wire change in 9.0.0: result provenance (_meta) moved from the outer tools/call envelope into the payload, and lost its nestweaver.io/ prefix. The shape is now _meta: { scope, sources, stale_repos } — see crates/nestweaver-schema/src/provenance.rs. Raw HTTP MCP clients that read nestweaver.io/sources off the envelope must be updated.

The MCP server automatically starts a background daemon that owns the database. Multiple MCP servers, CLI commands, and IDE integrations can share the same database concurrently without lock contention. The daemon exits after 1 hour of inactivity.

nestweaver daemon status --db ./nestweaver.lbug   # check daemon state
nestweaver daemon stop --db ./nestweaver.lbug     # stop the daemon manually
pgrep -af "nestweaver daemon"                     # find running daemons (Linux)

43 tools including type-aware context retrieval, confidence-weighted impact analysis (impact_score shows how strongly changes propagate), investigation bundles, co-change detection, dead code analysis, community detection, and vault/notes integration. Use --tools to expose only the tools you need. The --tools/--lite allowlists are enforced on every transport (local stdio, daemon proxy, hybrid, and MCP-over-HTTP), and tool schemas validate their arguments — numeric bounds (e.g. token_budget 1–16000, depth/max_depth 1–15) are enforced and unknown argument names are rejected instead of silently ignored.

Key capabilities

  • Type-aware call resolution — AST-extracted type bindings (annotations, constructors, self/this, return types) resolve obj.method() calls to the correct target class
  • Confidence-weighted blast radius — impact_score decays multiplicatively through edges; low-confidence paths are pruned
  • Co-change mining — Jaccard-scored file pairs from git history surface files that always change together
  • MRO walk — inherited methods resolved via class hierarchy traversal (depth 5, cycle-safe)

External MCP servers can be configured in your instance config with timeout_secs (default 30):

[[mcp_servers]]
name = "wiki-mcp"
command = "wiki-mcp"
timeout_secs = 60

Web UI

A search-first, task-lens workspace over your code+notes graph, powered by Three.js/React-Three-Fiber. The landing view is a repo-galaxy constellation — one luminous cluster per repository — rendered dark-first with selective HDR bloom, in-scene SDF labels, and a procedural nebula backdrop. Everything encodes meaning: color = kind, size = importance, and Spark-green convergence rings mark betweenness bridges (architectural chokepoints).

nestweaver ui --db ./nestweaver.lbug --port 8080
nestweaver ui --db ./nestweaver.lbug --port 8080 --watch  # live re-indexing

NestWeaver Web UI — repo-galaxy constellation with glowing hubs

NestWeaver Web UI — focused symbol with tri-panel source evidence

Work by task, not by graph theory:

  • Workspace scope — switch between all indexed content, a single repo, or a vault; every view carries an honest trust chip (local-only / federated, current / stale, partial / truncated)
  • Command bar (⌘K) + Search Phrases — plain-language queries resolve to typed scenes deterministically: impact of <symbol>, trace flow from <symbol>, callers of <symbol>, path from <A> to <B>, notes about <topic>, backlinks for <note>, hubs in <repo>, dead code in <repo>, stale repos
  • Task lenses — Overview, Context, Impact (layered blast-radius DAG with affected tests and local/org trust states), Trace (execution stepper), Repos, Features, Local neighborhood
  • Tri-panel workspace — activating a node opens a focused graph, synced source/note evidence, and a knowledge card (identity, role, evidence, relationships, trust, next actions), cross-highlighted
  • Graph / table / JSON parity — every result set is inspectable as a graph, an accessible table, or raw JSON with provenance/trust _meta
  • Deep links restore workspace scope, selected node, active lens, and representation mode

Visual & motion (all gated behind prefers-reduced-motion, which the UI auto-detects):

  • Selective HDR bloom via Khronos PBR-Neutral tone mapping — loud only on focus, hubs, and bridges; the ambient field stays calm
  • In-scene SDF text labels with collision-aware placement (labels never overlap nodes) and a landmark hierarchy that reveals detail on zoom
  • Per-galaxy glowing edge web, hub coronas, and settle-and-freeze force layout that preserves spatial memory across re-indexing
  • Signature moments: repo-galaxy ignition on load and a focus impact-ripple that traces blast radius
  • Community overlay (Louvain), minimap, and an explicit System / Light / Dark theme control

Accessibility: all six task journeys have a keyboard-only path; reduced-motion preserves every static meaning channel; graph answers always have a table/JSON equivalent; a screen-reader landmark summary mirrors the canvas.

WASM mode — Append ?engine=wasm to load a WebAssembly copy of the graph snapshot. The browser downloads a MessagePack snapshot and the status bar shows its node and edge counts. Queries, including PPR, run on the server. Requires building the wasm first (use --remap-path-prefix so the build machine's home path isn't baked into the artifact): RUSTFLAGS="--remap-path-prefix=$HOME=/build" wasm-pack build crates/nestweaver-wasm --target web --out-dir ../../crates/nestweaver-web/frontend/src/wasm.

Keyboard shortcuts (press ? in the UI for the full list):

  • 1–6 — switch task mode (Overview, Context, Impact, Repos, Features, Local)
  • ⌘K — open the ask / Search-Phrase command bar · / — focus search
  • ⌘L — cycle graph / list / matrix representation · ⌘⇧G — toggle zen (canvas-only) layout
  • I — impact of selected · P — path from selected · M / C / T — minimap / communities / tags
  • ⌘Z / ⌘⇧Z — navigate history back / forward · Esc — clear selection

Architecture

Cargo workspace with 15 crates compiling to a single static binary + optional WASM module
CrateDescription
nestweaver-schemaNode/edge types, UIDs, confidence scoring, schema versioning
nestweaver-parserTree-sitter + regex parsing for 32 languages
nestweaver-resolverCross-file symbol resolution with import graphs, monorepo workspace packages, and tsconfig path aliases
nestweaver-storeLadybugDB graph store, PageRank, hybrid search
nestweaver-storagePluggable snapshot storage backends (local, S3, GitLab)
nestweaver-engineIndexing pipeline, query dispatch, config, snapshots, LLM integration
nestweaver-algorithmsPure-compute graph algorithms (PPR, impact BFS) — WASM-compatible, no I/O
nestweaver-embedLocal embedding models (candle; Metal GPU on macOS) for vector search
nestweaver-protogRPC service definition (protobuf) for daemon IPC
nestweaver-federationFederation coordinator — upstream routing, health/ejection, two-tier merge, staleness (leaf; used by client + daemon-mode mcp)
nestweaver-daemonBackground daemon — owns the database, serves gRPC over Unix socket
nestweaver-clientDaemon client with auto-start, flock-based race prevention, version check
nestweaver-mcpMCP server — proxies tool calls through the daemon
nestweaver-webWeb UI (Three.js/R3F) and Axum API backend
nestweaver-wasmBrowser-side WASM module wrapping nestweaver-algorithms
schema              (zero internal deps)
  <- parser
  <- resolver
  <- store
algorithms          (zero internal deps — WASM target)
  <- wasm
storage             (zero internal deps)
proto               (generated gRPC types)
federation          (leaf: schema + proto — upstream routing/merge/staleness)
       <- engine <- (parser, resolver, store, storage, algorithms)
            <- daemon <- (engine, store, mcp, proto)
            <- client <- (proto, daemon, federation)
            <- mcp    <- (engine, store, schema; proto + federation under the `daemon` feature)
            <- web

Performance

71ms query p50
Next.js — 29,402 files

632ms incremental re-index
Tailwind CSS — no full rebuild needed

14.8M edges extracted
Elasticsearch — 511K symbols, 43K files

Benchmark results (NestWeaver vs Graphify)

Query Speed (p50)

RepositoryFilesNestWeaverGraphify
Tailwind CSS542157ms185ms
Deno14,13682ms1,355ms
Next.js29,40271ms2,440ms
Elasticsearch43,806617mscrashed

Indexing Speed

RepositoryNestWeaverGraphify
Tailwind CSS3.6s2.5s
Deno51s33s
Next.js33s111s
Elasticsearch3,462scrashed

Incremental re-indexing (NestWeaver only — Graphify requires full re-index): 632ms (Tailwind), 4.0s (Next.js), 73s (Elasticsearch).

Graph depth: NestWeaver extracts 142K symbols / 280K edges on Deno (vs Graphify's 76K / 177K). On Elasticsearch: 511K symbols, 14.8M edges.

Result quality: NestWeaver returns ~30 connected symbols per query ranked by PageRank with full signatures. Graphify returns file-level nodes with 9-15% garbage stubs.

Benchmarked in daemon mode on M3 Pro (36 GB). See benchmarks/ to reproduce.

Contributing

See CONTRIBUTING.md for guidelines on building, testing, and submitting changes.

License

MIT


kehl.io
Built by kehl.io

NPM
nestweaver
Install Command
npm install nestweaver
Runtime: npx