Nectar architecture

The technical picture of Nectar for builders and auditors: identity, description, storage, the watcher, and how recall composes with Honeycomb. Grounded in the Nectar technical manual.

Related:

• What is Nectar?
• Nectar command reference
• How Nectar compares

---

#Overview

Nectar is an independent workload daemon that gives every file in a project a stable identity and a plain-language description, and exposes both to hybrid recall. It composes with Honeycomb at the data layer by sharing the same Deep Lake datasets, but it runs as its own supervised daemon, not a Honeycomb subsystem.

#Identity: minted, not derived

A nectar is a 26-character ULID minted once by the daemon and persisted in Deep Lake. It is deliberately not derived from the file's contents (so edits do not churn it) and not derived from its path (so moves do not kill it). A content hash, computed with sha256, is the secondary version key; it changes on every edit. Content-derived identity was considered and rejected, because a hash cannot provide stable identity across edits without a separate anchor.

Source-embedded identity, such as writing a serial number into the file, was also considered and rejected: it collides with license headers, creates merge conflicts, fails on files with no comment syntax, and needs a sidecar anyway.

#Re-association: the five-step ladder

When a file changes or moves, the daemon decides whether it is the same file and reattaches it to its existing identity. It walks a ladder, first match wins:

1. Path, modified-time, and size fast path.
2. Path match with changed content.
3. Exact content-hash match, for a clean move.
4. Fuzzy content match, for a move plus an edit.
5. Mint a fresh identity.

Low-confidence fuzzy matches at step four are never auto-claimed. They route to human review via nectar review-matches, because a wrong association would corrupt the file's history chain.

#Description: per file, by a language model

A long-context language model writes a title of up to 80 characters, a one to three sentence description, and a few concept tags per file. Descriptions are produced lazily and in batches: 30 to 50 small files per call, large files one at a time. The description is at file granularity, not per-symbol chunk; symbol-level structure is left to the code graph that ships in the stack. The description model is a long-context model reached through a gateway you configure.

#Storage: two Deep Lake tables

• hive_graph: one row per logical file, holding identity and provenance only, keyed by the nectar.
• hive_graph_versions: append-only, keyed by the pair of nectar and content hash, one row per observed state, carrying the path, metadata, title, description, concept tags, and a 768-dimension embedding.

Deep Lake gives identity joins and vector search in one engine, with no second database and no sidecar. The append-only history makes re-association auditable. With embeddings off, recall degrades gracefully to keyword search over a null embedding column, with no error.

#The watcher

The watcher uses the platform's native file-watch mechanism plus a debounce, mirroring Honeycomb's pattern. Rapid saves collapse into a single change signal, and re-description happens only after a pause and only when the meaning crossed a threshold. The database sees one row per meaningfully distinct content state, not one per keystroke-save.

#Recall: a guarded arm in hybrid recall

nectar search, and the daemon's search endpoint, run a per-arm guarded keyword-plus-vector query over described files, fused by reciprocal rank fusion, with a silent keyword fallback when embeddings are off. Those same hits also surface as a fourth arm inside Honeycomb's cross-memory recall, alongside sessions, distilled memories, and skills. The 768-dimension embedding matches Honeycomb's session and memory embeddings, so one pipeline can query all of them.

#The projection lockfile

.honeycomb/nectars.json is a regenerable projection of Deep Lake state: a content-hash-keyed map of the nectar, title, description, and concepts for the latest version of each file. It is a projection, not a sidecar, enforced by three rules: Deep Lake is written first, the file is never hand-edited, and it is fully regenerable from Deep Lake alone. It is committed for portability, so a fresh clone re-derives identity from it with zero model calls and zero network. It omits full version chains, embeddings, and internal ids.

#The daemon

nectar daemon binds 127.0.0.1:3854, serves /health, registers with Doctor for supervision, installs as an OS service, and holds a single-instance lock. It sits in the three-role topology: Doctor supervises, Hive portals, workloads work.

#Boundaries

Nectar ships no MCP server of its own. Its results reach assistants through Honeycomb's existing recall tools, so there is one memory boundary, not two. It never mutates source; the only file it writes is the projection.

#License

Released under the GNU Affero General Public License, version 3.0 or later.