feat: memory anchors — independent searchable file bookmarks - #18
Merged
Conversation
First-principles redesign of how an Agent reaches file content through NMG. Drops the full-text file index (file-content-source) in favor of sparse, Agent-authored anchors: independent searchable rows (path, snippet, label), content-anchored (relocation not line numbers), linked to memory via the open-string markers channel (anchor_ref). Writing is active; recall is active + passive. Surveyed haido/gptme/agentic-bookmarks/ai-memory for the anchor + objective-staleness pattern. File-content-source-design is marked superseded; its 'files are not memory' and separated-presentation conclusions carry forward.
Implements the memory-anchors design (docs/design/memory-anchors-design.md): file bookmarks attached to memories, searchable alongside memory. - store: anchors table + anchors_fts (label/snippet) in schema; remember() writes anchor rows and auto-appends anchor_ref markers (open markers channel, zero migration on existing data); searchAnchors/getAnchorsByIds in retrieval mixin. Duplicate memory writes do not duplicate anchors. - service: remember params accept anchors; search attaches resolved anchor hits (snippet relocated to line against projectDir, stale when absent). - CLI: --anchor PATH::SNIPPET[::LABEL] on remember; ANCHORS: section on human search output. - DSH plugin: nmg_remember accepts anchors; search surface renders anchor=path:line entries. - tests: anchors.test.ts covers write/markers/search/duplicate paths. Complexity gate passes; write path refactored into #planAnchorWrites / #insertAnchorRows / mergeMarkers to hold rememberInner at baseline.
- remove unused AnchorRecord import in service - extract readLinesSafe module helper (no useless assignment) - prettier formatting on touched files
Template guides PR description (what/why/changes) and pre-merge checks: local quality (verify:static, test:product), RCP (board goal, agent:verify reconcile, owned files only), and CI completion via the CI Status Snapshot (.nmg-ci/status.json conclusion=success, failures=[]) instead of polling individual jobs. Aligns with ci-cd-and-quality.md proof-before-trust.
13 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
First-principles redesign of how an Agent reaches file content through NMG (docs/design/memory-anchors-design.md). Drops the full-text file index in favor of sparse, Agent-authored anchors (bookmarks) as an independent searchable source.
Problem: the Agent repeatedly searches around for things it already knows exist. NMG memory stores "there is this thing", but not "where it lives". The old file-content-source (full-text file index) was usable but maintenance-heavy (scope file, incremental crawler, file FTS) and returned unanchored trigram fragments.
Design (first principles): three layers — memory (long-lived, "there is this thing"), anchor/bookmark ("its content is here"), file (content host). The Agent remembers that a thing exists; anchors cheaply and objectively reach its content. No need to remember file:line (high-churn, fragile) — the anchor relocates by content snippet.
Changes
anchorstable + FTS (label/snippet);remember()writes anchor rows and auto-appendsanchor_refmarkers (open markers channel, zero migration);searchAnchors/getAnchorsByIds.--anchor PATH::SNIPPET[::LABEL]on remember;ANCHORS:section on human search output.Verification
ANCHORS: docs/design/memory-anchors-design.md:43 anchors 设计决策节(snippet resolved to line 43).Supersedes the file-content-source full-text file index design (#17).