@restregular/dsh-memory 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 restregular
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,70 @@
1
- # Temporary Holding Version
1
+ # @restregular/dsh-memory
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ DeepSeek Harness 的本地长期记忆插件(核心包):JSONL 存储 + 本地向量检索 + 四个模型工具 + 自动召回注入。
4
+
5
+ ## 安装
6
+
7
+ 装进任意 DSH profile(例如桌面端 `~/.dsh/profiles/desktop`,Web 端 `~/.dsh/profiles/web`):
8
+
9
+ ```bash
10
+ pnpm add @restregular/dsh-memory
11
+ ```
12
+
13
+ 本包同时提供三个 loader entry,装好后自动生效(bundle patch 已随包分发):
14
+
15
+ | entry id | 作用 |
16
+ | --- | --- |
17
+ | `dsh-memory-local` | 提供 `memory` 服务:存储、检索、向量回填 |
18
+ | `dsh-tool-memory` | 注册 `memory_save` / `memory_search` / `memory_list` / `memory_forget` 四个工具 |
19
+ | `dsh-memory-inject` | 在 `agent/pre-step` 注入召回块(可选,可关) |
20
+
21
+ > 管理面板是独立包:**@restregular/dsh-memory-panel**(设置页里查看/编辑/删除记忆,并手动启停向量服务)。
22
+
23
+ ## 配置
24
+
25
+ patch 里给 `dsh-memory-local` 传配置即可(默认值通常够用):
26
+
27
+ ```yaml
28
+ - id: dsh-memory-local
29
+ config:
30
+ storeDir: '~/.dsh/memory-store' # 默认 <home>/.dsh/memory-store
31
+ scopes: { global: true, project: true }
32
+ retrieval:
33
+ topK: 5
34
+ vector:
35
+ enabled: true
36
+ endpoint: 'http://127.0.0.1:8078/v1/embeddings'
37
+ model: bge-m3
38
+ dims: 1024
39
+ timeoutMs: 300 # 交互检索预算(要紧)
40
+ writeTimeoutMs: 10000 # 保存时嵌整条记录
41
+ backfillTimeoutMs: 30000 # 批量回填
42
+ backfillMaxChars: 8000
43
+ llm: { enabled: false } # LLM 重排(可选)
44
+ limits: { maxRecordsPerScope: 2000, maxRecordChars: 4000 }
45
+ secrets: { enabled: true, mode: refuse } # 拒绝写入疑似凭据
46
+ ```
47
+
48
+ ### 本地向量服务(可选)
49
+
50
+ 不配向量服务时,检索自动降级为纯词法(IDF + CJK bigram),功能不受影响。要启用语义检索,指向任意 OpenAI 兼容的 `/v1/embeddings` 服务(推荐 `llama-server` + BGE-M3):
51
+
52
+ ```yaml
53
+ vector:
54
+ spawn: # 让插件托管 llama-server 进程(opt-in)
55
+ enabled: true
56
+ exe: '/path/to/llama-server.exe'
57
+ model: '/path/to/bge-m3-Q4_K_M.gguf'
58
+ cwd: '/path/to/llamacpp' # 该目录须含 llama-server-impl.dll
59
+ logFile: '/path/to/llama-server.log'
60
+ threads: 6
61
+ ```
62
+
63
+ `spawn.enabled: true` 时:应用启动后台拉起、应用退出自动关闭;已在跑的实例(有 PID 文件)会被接管,没有 PID 文件的外部实例不接管。也可在面板里手动开关。
64
+
65
+ ## 说明
66
+
67
+ - 存储为每作用域一个 JSONL + `.vec` 向量边车(含模型/维度身份头,不匹配自动重建)。
68
+ - 记忆分 `global` 与 `project:<cwd>` 两类作用域。
69
+ - 只在插件自己的生命周期内工作:任何异常都被吞掉并记日志,绝不让 DSH 启动失败。
70
+ - License: MIT
@@ -0,0 +1,10 @@
1
+ # @restregular/dsh-memory bundle patch: local memory provider + model-facing tools + recall injection.
2
+ # 三个 entry 共用本包,但本包不声明 dsh.client —— 声明了客户端 bundle 的包只允许一个活跃
3
+ # entry(dsh-client-modules: "resolves from multiple active Loader sources")。
4
+ - insert:
5
+ - id: dsh-memory-local
6
+ name: '@restregular/dsh-memory'
7
+ - id: dsh-tool-memory
8
+ name: '@restregular/dsh-memory/tools'
9
+ - id: dsh-memory-inject
10
+ name: '@restregular/dsh-memory/inject'
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Cordis wiring for dsh-memory-inject. Loaded only inside DSH: hooks the
3
+ * documented agent/pre-step waterfall and appends a user-role recall message
4
+ * carrying the retrieved memories.
5
+ *
6
+ * Message construction MUST go through createUserMessage: the loop reads
7
+ * `decision.kind` and downstream consumers read `message.source.kind`, so a
8
+ * hand-rolled `{ role, content }` object aborts the turn with
9
+ * "Cannot read properties of undefined (reading 'kind')" (incident 2026-10-10).
10
+ * The reference implementation is the official dsh-time-context plugin.
11
+ *
12
+ * Memory is an OPTIONAL dependency (ctx.get) by design — this plugin must not
13
+ * sit PENDING when no provider is loaded; it just stays passive.
14
+ */
15
+
16
+ import { createUserMessage } from '@deepseek-ai/dsh-llm'
17
+
18
+ import { MemoryInjector, defaultInjectConfig, } from './inject.js'
19
+
20
+
21
+
22
+
23
+
24
+
25
+ export const name = 'dsh-memory-inject'
26
+
27
+ export function apply(ctx , config = {}) {
28
+ const cfg = {
29
+ enabled: config.enabled ?? defaultInjectConfig.enabled,
30
+ tokenBudget: config.tokenBudget ?? defaultInjectConfig.tokenBudget,
31
+ topK: config.topK ?? defaultInjectConfig.topK,
32
+ }
33
+
34
+ // One injector per activation: its repeat-suppression state must live across
35
+ // the steps of a turn (a per-step instance would re-inject every step).
36
+ const injector = new MemoryInjector(
37
+ async (query, signal) => {
38
+ const memory = ctx.get('memory')
39
+ if (!memory?.search) return []
40
+ return memory.search({ text: query, signal, topK: cfg.topK })
41
+ },
42
+ cfg,
43
+ )
44
+
45
+ ctx.on('agent/pre-step', async (input, next) => {
46
+ // Runs outermost (prepend), so `next()` yields the fully assembled decision.
47
+ const decision = await next()
48
+ // A rejected step must pass through untouched — never rebuild the decision.
49
+ if (!decision || decision.kind === 'reject' || input.signal?.aborted) return decision
50
+ // optional capability: absence (or partial load) → pass through untouched
51
+ if (!ctx.get('memory')) return decision
52
+
53
+ const text = await injector.maybeInject(
54
+ { messages: input.messages , signal: input.signal },
55
+ { messages: decision.messages },
56
+ )
57
+ if (!text) return decision
58
+ const message = createUserMessage({
59
+ content: [{ type: 'text', text }],
60
+ source: { kind: 'memory', form: 'recall' },
61
+ })
62
+ // Last-resort guard: a malformed message aborts the whole turn downstream
63
+ // (consumers read message.source.kind), so never publish one.
64
+ if (!isWellFormedMessage(message)) return decision
65
+ return { ...decision, messages: [...decision.messages, message] }
66
+ }, { prepend: true })
67
+ }
68
+
69
+ const VALID_BLOCK_TYPES = new Set(['text', 'reasoning', 'image', 'file', 'tool-call', 'tool-addition', 'tool-removal'])
70
+
71
+ /** Structural check against the host Message contract (id/role/content/source.kind). */
72
+ function isWellFormedMessage(message ) {
73
+ const m = message
74
+ if (!m || typeof m.id !== 'string' || typeof m.role !== 'string') return false
75
+ if (!Array.isArray(m.content) || m.content.length === 0) return false
76
+ if (!m.content.every((block) => typeof (block )?.type === 'string' && VALID_BLOCK_TYPES.has((block ).type))) return false
77
+ const source = m.source
78
+ return typeof source?.kind === 'string'
79
+ }
80
+
81
+
82
+ //# sourceURL=D:\.deepseek\memory-plugin\packages\memory-inject\src\apply.ts
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Memory injection logic (M3) — pure functions, no cordis imports.
3
+ *
4
+ * Injection shape follows the official docs: a user-role message whose content
5
+ * is a single `context` block with `contextForm: 'recall'`, prepended to the
6
+ * messages that enter the step via the agent/pre-step waterfall.
7
+ */
8
+
9
+ import { estimateTokens } from '../provider/rerank.js'
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+ export const defaultInjectConfig = {
20
+ enabled: true,
21
+ tokenBudget: 500,
22
+ topK: 5,
23
+ }
24
+
25
+ /** Minimal structural view of the messages we inspect (role + text blocks). */
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+ /**
41
+ * Extract the retrieval query: the text of the LAST user message. Synthetic
42
+ * context injections (file notices etc.) are user-role too, so scanning from
43
+ * the end finds the freshest human-visible input; empty text → no injection.
44
+ */
45
+ export function pickQueryText(messages ) {
46
+ for (let i = messages.length - 1; i >= 0; i--) {
47
+ const m = messages[i]
48
+ if (m.role !== 'user') continue
49
+ const text = (m.content ?? [])
50
+ .filter((b) => b.type === 'text' && typeof b.text === 'string')
51
+ .map((b) => b.text )
52
+ .join(' ')
53
+ .trim()
54
+ if (text) return text
55
+ }
56
+ return ''
57
+ }
58
+
59
+ /** Render hits into a recall text block, greedily within the token budget. */
60
+ export function renderRecallBlock(hits , cfg ) {
61
+ if (hits.length === 0) return null
62
+ const header = '以下是与此请求可能相关的长期记忆,供参考(可用 memory_search 核实,用 memory_forget 删除):'
63
+ let tokens = estimateTokens(header) + 4
64
+ const lines = []
65
+ for (const h of hits.slice(0, cfg.topK)) {
66
+ const line = `- ${h.record.content.replace(/\s+/g, ' ').slice(0, 300)}`
67
+ const cost = estimateTokens(line) + 1
68
+ if (tokens + cost > cfg.tokenBudget) break
69
+ lines.push(line)
70
+ tokens += cost
71
+ }
72
+ if (lines.length === 0) return null
73
+ return { text: `${header}\n${lines.join('\n')}`, tokens }
74
+ }
75
+
76
+ /** The context block we prepend (matches the documented ContextForm 'recall'). */
77
+ export function recallText(text ) {
78
+ return text
79
+ }
80
+
81
+ /**
82
+ * Turn-agnostic injector: searches memory for the step's query and returns the
83
+ * recall text to append. The host middleware (apply.ts) wraps that text into a
84
+ * real message via createUserMessage — a bare {role, content} object is NOT a
85
+ * message and crashes the loop (see the 2026-10-10 incident below).
86
+ *
87
+ * Repeated identical injections are suppressed so a multi-step turn does not
88
+ * repeat the same block before every model call.
89
+ */
90
+ export class MemoryInjector {
91
+ lastText = ''
92
+ search
93
+ cfg
94
+
95
+ constructor(
96
+ search ,
97
+ cfg ,
98
+ ) {
99
+ this.search = search
100
+ this.cfg = cfg
101
+ }
102
+
103
+ async maybeInject(
104
+ input ,
105
+ _decision ,
106
+ ) {
107
+ if (!this.cfg.enabled) return undefined
108
+ const query = pickQueryText(input.messages)
109
+ if (!query) return undefined
110
+
111
+ let hits
112
+ try {
113
+ hits = await this.search(query, input.signal)
114
+ } catch {
115
+ return undefined // retrieval failure never breaks the agent loop
116
+ }
117
+
118
+ const block = renderRecallBlock(hits, this.cfg)
119
+ if (!block || block.text === this.lastText) return undefined
120
+ this.lastText = block.text
121
+
122
+ return block.text
123
+ }
124
+ }
125
+
126
+
127
+ //# sourceURL=D:\.deepseek\memory-plugin\packages\memory-inject\src\inject.ts
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Cordis wiring for dsh-memory-local. Loaded only inside DSH.
3
+ *
4
+ * Per the official docs:
5
+ * - registers the service so consumers reach it as `ctx.memory`
6
+ * - the LLM rerank caller adapts `ctx.llm` (one-shot GenerateOptions with
7
+ * RequestUserInput) — attached lazily via ctx.get, so the plugin never sits
8
+ * PENDING just because no LLM adapter is loaded
9
+ */
10
+ import { Service, } from '@deepseek-ai/cordis'
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+ import { LocalMemoryService, } from './index.js'
19
+
20
+
21
+ export const name = 'dsh-memory-local'
22
+
23
+ export class CordisMemoryService extends Service {
24
+ impl
25
+
26
+ constructor(ctx , config = {}) {
27
+ super(ctx, 'memory')
28
+ this.impl = new LocalMemoryService(config)
29
+ ctx.effect(() => () => this.impl.flushSync())
30
+ this.attachRerank(ctx, config)
31
+ }
32
+
33
+ /**
34
+ * Wire the rerank stage to ctx.llm when both it and a model are configured.
35
+ * Uses the documented one-shot shape: GenerateOptions + RequestUserInput,
36
+ * consuming `text-delta` chunks until finish.
37
+ */
38
+ attachRerank(ctx , config ) {
39
+ const llmCfg = config.retrieval?.llm
40
+ if (!llmCfg?.enabled || !llmCfg.model) return
41
+ const llm = ctx.get('llm')
42
+
43
+
44
+ if (!llm?.stream) return
45
+ this.impl.setLlmInvoke(async ({ system, prompt, signal }) => {
46
+ const chunks = []
47
+ const stream = llm.stream({
48
+ provider: llmCfg.provider || 'deepseek',
49
+ model: llmCfg.model,
50
+ system,
51
+ messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
52
+ maxTokens: 300,
53
+ temperature: 0,
54
+ signal,
55
+ })
56
+ for await (const chunk of stream) {
57
+ if (chunk.type === 'text-delta' && typeof chunk.textDelta === 'string') chunks.push(chunk.textDelta)
58
+ }
59
+ return chunks.join('')
60
+ })
61
+ }
62
+
63
+ save(input ) {
64
+ return this.impl.save(input)
65
+ }
66
+
67
+ /** Direct store access for server-side consumers (e.g. the memory panel). */
68
+ get store() {
69
+ return this.impl.store
70
+ }
71
+
72
+ /** Embedding-backend lifecycle, exposed for the memory panel's buttons. */
73
+ embedServerStatus() {
74
+ return this.impl.embedServerStatus()
75
+ }
76
+
77
+ startEmbedServerManually() {
78
+ return this.impl.startEmbedServerManually()
79
+ }
80
+
81
+ stopEmbedServerManually() {
82
+ return this.impl.stopEmbedServerManually()
83
+ }
84
+
85
+ search(query ) {
86
+ return this.impl.search(query)
87
+ }
88
+
89
+ forget(input ) {
90
+ return this.impl.forget(input)
91
+ }
92
+
93
+ list(input ) {
94
+ return this.impl.list(input)
95
+ }
96
+ }
97
+
98
+ export function apply(ctx , config = {}) {
99
+ class ScopedMemoryService extends CordisMemoryService {
100
+ constructor(ctx2 ) {
101
+ super(ctx2, config)
102
+ }
103
+ }
104
+ ctx.plugin(ScopedMemoryService)
105
+ }
106
+
107
+
108
+ //# sourceURL=D:\.deepseek\memory-plugin\packages\memory-local\src\apply.ts