HologramAgent-DSH-Memory-Port

把 HologramAgent 的记忆系统移植到 dsh 插件。本仓分两部分：

1. 调研报告（已交付）
   • docs/feasibility.md — 三层记忆移植可行性评估（结论：只能做子集，L2+L3 可移植，L1 抓不住）
   • docs/shadow-context.md — 影子上下文方案核实（结论：路线② preset 可行，路线① 只是看着可行）
2. MVP 阶段 A 实现（本文件以下内容）— 1–2 天切片：块能进 dsh、能被召回、能进 prompt，不引入 embedding

---

dsh-memory（阶段 A）

HologramAgent-style block memory for dsh, as a dsh plugin. This is phase A of the MVP described in docs/feasibility.md §7.1 — the smallest slice that proves the whole chain works:

commit a block  →  store it durably  →  recall it  →  get it into the model's prompt

Deliberately not included: embedding providers, vectors, the L1 eviction flow, media blocks. Each is blocked or out of scope for a 1–2 day slice; see What this slice does not do.

---

★ Read this before touching injection

dsh has two injection hooks that look interchangeable and are not. Getting this wrong silently corrupts the conversation log.

hook	receives this turn's input?	durable side effect
ctx.systemPrompt.context({ text })	No — AssembleContext is {scope, signal} + a merged-in agent	appends a runtime-context snapshot
ctx.on('agent/pre-step')	Yes — payload carries decision.messages	every message you return is appended as a durable user/message

Evidence, verified in the installed harness (not inferred):

• dsh-system-prompt/lib/types/index.d.ts:37-44 — AssembleContext has only scope and signal (agent is added by dsh-agent's declaration merging; still no messages).
• dsh-agent-loop/lib/index.js:902-934 — preStep() claims the inbox, calls systemPrompt.assemble(), then runs the agent/pre-step waterfall with those messages.
• dsh-agent-loop/lib/index.js:1066-1073 — the loop then does session.append('user/message', message, { surfaceOp: 'append' }) for each returned message.

Consequences, and how this plugin uses them:

• The input-independent index (a block count, "memory exists, here's the tool") goes through systemPrompt.context. It cannot see the current question, so it must not pretend to be a recall result.
• Per-turn recall goes through agent/pre-step, because that is the only hook that sees the input. Recall is prepend: true so it runs before listeners that may want the final word.
• Because pre-step output is durable, injected recall becomes part of the conversation history. That is acceptable here (it is honest: the model saw it), but it means this plugin is not a shadow-context mechanism. For that distinction see docs/shadow-context.md §1.3.

There is no hook for "the context is about to overflow, please evict something", and no waterfall that can rewrite a loop-built request (llm/stream receives a deep-frozen GenerateOptions for loop requests — dsh-llm/lib/types/index.d.ts:37-42).

---

Install

# from this repo
npm install                    # nothing to install; dsh packages are peers

The plugin needs node:sqlite (built into Node ≥ 22.5). On Node 22.23 it works behind an ExperimentalWarning only — no --experimental-sqlite flag.

Mount it in a dsh composition:

- id: memory
  name: dsh-memory
  config:
    path: /path/to/memory.db     # optional; defaults to <cwd>/.dsh-memory/memory.db
    topK: 3                      # optional; recall hits injected per turn
    inject: true                 # optional; false = tool only, no auto-recall
    toolName: stablemem_commit   # optional; must be unique per tool layer

Use

The model gets one tool:

stablemem_commit({ text, source?, scene? })

and, once at least one block exists, a constant prompt context line telling it that durable memory is available.

Recall runs automatically each turn: the last user message is used as the query, FTS5 + exact-symbol pinning selects up to topK blocks, and they are injected as one attributed user message:

[Memory · dsh-memory] Recalled from durable block memory — these are PAST notes, not the current conversation.
[1] (exact 1.01) 值班室分机号 4324，值班人 老周

Programmatic use (another plugin, or a preset subtree):

ctx.stablemem.commit({ text: 'etcd 集群端口 2379', source: 'ops' })
ctx.stablemem.recall('etcd 端口', 5)
ctx.stablemem.link({ sourceKind: 'block', sourceId: a, targetKind: 'block', targetId: b, type: 'supersedes' })

---

Schema

Three tables, mirroring HologramAgent's (internal/memory/graph.go:2577, :320, centroid_store.go:58), restricted to the text modality:

table	purpose	notes
memory_blocks	the block payload	text_content is the body; source / scene / semantic_type mirror HA's columns
memory_block_edges	structural + semantic edges	unique per (source_kind, source_id, target_kind, target_id, type)
graph_centroid	vector-space centering	created empty — phase B writes it; creating it now avoids a migration
memory_blocks_fts	FTS5 index over text_content	unicode61 remove_diacritics 2

memory_blocks.id is content-addressed (blk_ + sha256(text)[:12], ported from distill.BlockID, internal/memory/distill/blocks.go:99), so re-committing identical text is idempotent and never blanks existing metadata.

---

Recall design, and why there are no vectors yet

This slice ports HologramAgent's symbol path, not its vector path.

docs/zh/recall-capability-tiers.md measures four query shapes. The one that works best in production is 形态 1 (queries carrying an exact token: port, IP, path, version) — which is pure symbol matching. The one that needs vectors is 形态 3 (pure generic description), and it is the weakest even with vectors (target block ranked 389/2686). So dropping embeddings here costs the tier that was already marginal, not the tier that carries the product.

Scoring follows HA exactly where it matters:

• An exact numeric hit is a boolean pin (1.0 + lexical*0.01), never a weight. Folding it into a weighted sum makes it lose to noise — the regression documented at internal/memory/fusion.go:43-49.
• A matched word is a coverage signal, not an exact hit.
• Single-character symbols are rejected (abstain.go:115 "单字不成符号"); without that gate a query like billing0 yields a bare 0 that "exactly" matches every block containing a zero.
• A matched word prefers blocks where it is not a prefix of a longer word (billing should beat billing2), loosely mirroring isCrossWordTailMatch (distill/split.go:383).

Two documented gaps, asserted rather than hidden (see checkpoint V2):

gap	why	when
纯泛化描述 queries ("公网地址是什么")	needs vectors	phase B
「库里没有」detection (abstention)	needs either vectors or a real CJK tokenizer	phase B/C
CJK segmentation	unicode61 keeps a CJK run as ONE token; compensated by a 2..4-char sliding-window fallback ported from cjkWindows (fusion.go:240)	phase C

---

Three harness constraints this slice discovered

Each was found by a failing test, not by reading types — they are recorded here because they will bite anyone writing a second dsh service plugin.

1. A cordis service must not use JS #private fields. ctx.stablemem is a proxy, not the instance you constructed, and private fields are bound to the declaring object: Cannot read private member #store from an object whose class did not declare it. Keep service state in ordinary properties.

2. isolate() does not partition prompt-context names or tool names. It partitions service lookups. Two instances in one realm still collide on systemPrompt.context({name}) (dsh-system-prompt/lib/index.js:204) and tools.register unless the names differ. Hence the configurable toolName, and the prompt-context name derived from the database path (memory:index:<key>), which stays unique and stable.

3. ctx.systemPrompt.getContextOrder() is an allocator, not a free constant. Prefer a named slot (WEB_SURFACE) over a magic number; the numeric constants are private to the package.

---

What this slice does not do

not done	why	where it lands
embeddings / vectors	no embedding service in dsh (docs/feasibility.md §5.1)	phase B
evicting L1 context into memory	dsh's compaction is summary-replacement, and CompactionTrigger carries no query (§5.3)	replaced by shadow-context + preset
media blocks	dsh attachment is CAS; HA requires bytes inside the block (§5.4)	not planned
cross-session / cross-agent memory	one sqlite file per config.path	phase D
abstention	needs vectors or a real tokenizer	phase B/C

---

Verify

npm test          # 26 tests: store, recall, plugin wiring, real loader, isolation
npm run check     # 8 checkpoints with human-readable evidence (V1–V5 + mutations)

npm run check prints one line of evidence per checkpoint. The mapping to docs/feasibility.md §7.1:

checkpoint	proves
V1	node:sqlite opens, WAL applies, 100 writes round-trip
V2	recall quality per capability tier: tiers 1–2 must pass, tiers 3–4 pinned as gaps
V3	systemPrompt.context exposes agent and cannot see this step's messages
V3b	agent/pre-step injection lands in the accepted batch with our source.kind
V3b†	mutation — silencing recall makes V3b fail (the test can turn red)
V4	tools.register schema + render contract, executed end to end
V5	fiber disposal closes the handle; the file is reopenable
A5†	mutation — containment-only recall loses discrimination (why FTS is primary)

Expectations from a real run

  ✔ V1  journal=wal, rows=100, mid-batch row=blk_cad13afe6824, file on disk
  ✔ V2  tier1(exact) 30/30 = 100% · tier2(domain) 20/20 = 100%
        · known gaps: 泛化查询→0 hit, 库里没有→0 hit (需向量，phase B)
  ✔ V3  AssembleContext keys = [agent] — no messages/input field
  ✔ V3b batch 2 msgs; injected kind=dsh-memory, carries "4324"
  ✔ V4  1 tool(s) visible; execute → "Committed block blk_0be019e8b0e4."
  ✔ V5  fiber dispose → handle closed; reopened same file successfully

8/8 checkpoints passed

---

Ported from HologramAgent

Source is read-only reference (/home/program/TrueAgent); nothing is vendored.

this repo	HologramAgent
lib/store.js BlockStore	memory.GraphDB.PutMemoryBlocks (internal/memory/block.go:203)
lib/store.js blockId	distill.BlockID (internal/memory/distill/blocks.go:99)
lib/recall.js querySymbols	memory.QuerySymbols (internal/memory/fusion.go:145)
lib/recall.js scoring / pin	memory.SymbolScore (fusion.go:284), pin at :427
lib/recall.js isNumericSymbol	fusion.go:316
lib/recall.js cjkNeedles	cjkWindows (fusion.go:240)
lib/recall.js single-char gate	AbstainCheck guard (abstain.go:115)
lib/index.js renderIndex header	crossModalMarkdown (internal/agent/core/crossmodal.go:256)

License

MIT