dsh-subagent-memory 0.2.0

package/README.md

@@ -0,0 +1,39 @@
+# Agent Memory（子代理记忆）
+
+给**子代理**用的工作记忆——单一职责：没有全局仓库、没有跨会话库、没有浏览器页面。
+
+## 能力
+
+**被动（子代理自己用）**：`memory_add` / `memory_list` / `memory_get` 三个工具，只能读写**调用者自己会话**的记忆。
+
+**主动（委派方或宿主插件）**：`ctx.agentMemory` 服务 API：
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `read` | `read(childId, callerId, {tag?})` | 读某子代理的记忆条目 |
+| `write` | `await write(childId, callerId, {title, content, tags?})` | 往某子代理记忆里写一条 |
+| `summary` | `summary(childId, callerId)` | 紧凑文本摘要，供委派方注入提示 |
+
+**API 安全（邻接校验）**：调用者只能触碰**自己直接父级**的子会话记忆——`sessions.get(child).header.parentSession` 必须等于 `callerId`（或 `callerId === childId` 自省）；未物化会话、非父子关系一律拒绝。
+
+**级联清理**：子代理结束（`subagent/end`）时自动删除其全部记忆。
+
+**能力发现**：向 `dsh-compat-layer` 的能力注册表声明 `agentMemory`（v2），其他插件可自动匹配发现，无需硬依赖本包。
+
+## 存储
+
+插件自身的 volatile 设置命名空间 `agent-memory`（官方运行时可变偏好管线），无需文件、无自定义协议。
+
+## 配套
+
+与 `dsh-subagent-pro` 自动匹配：装了本包后 subagent-pro 会多出一个 `subagent_memory` 工具（读某个子代理的记忆摘要）；不装则没有该工具，双方互不影响。
+
+## 安装
+
+桌面端：插件 → 添加插件 → 输入包名 `dsh-agent-memory`（或本地路径安装 tgz）。
+
+## English
+
+Narrow, subagent-scoped memory: three tools for a delegated child's own notes, an adjacency-checked service API (`read` / `write` / `summary`) for the delegating parent, cascade deletion when the child settles, and capability discovery through dsh-compat-layer. No global store, no browser page.
+
+License: MIT. Author: jd962.

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# Agent Memory — persistent install patch.
+# The settings namespace `agent-memory` (the memory store) is derived from the
+# row's volatile Config; the browser memory page rides the same row.
+- insert:
+    - id: agent-memory
+      name: 'dsh-subagent-memory'
+      config: {}

package/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="6" y="6" width="52" height="52" rx="8" fill="#1e293b"/>
+  <path d="M32 14 L36.5 24.5 L48 25.5 L39.5 33.5 L42 45 L32 39.5 L22 45 L24.5 33.5 L16 25.5 L27.5 24.5 Z" fill="#f59e0b"/>
+</svg>

package/index.js

@@ -0,0 +1,281 @@
+/**
+ * Agent Memory — subagent-scoped memory for DeepSeek Harness.
+ *
+ * SCOPE (deliberately narrow): only a SUBAGENT's own working memory. There is
+ * no global store, no cross-session library, no user lock, and no browser
+ * page - those were removed by design so this plugin owns exactly one thing:
+ * "what a delegated child learned while doing its job".
+ *
+ * Two consumption modes:
+ * - PASSIVE (the child itself): `memory_add` / `memory_list` / `memory_get`
+ *   tools write and read the CALLING session's own memory only.
+ * - ACTIVE (the delegating parent or any host plugin): the `ctx.agentMemory`
+ *   service API, which is adjacency-checked - a caller can only touch the
+ *   memory of a child it actually parents (`sessions.get(child).header.parentSession`
+ *   must equal the caller's session id, or the caller IS the child).
+ *
+ * Storage: this plugin's volatile settings namespace (`agent-memory`), the
+ * official runtime-mutable preference pipeline. Entries are cascade-deleted
+ * when the owning subagent settles (`subagent/end`), so a finished child never
+ * leaves orphaned notes behind.
+ *
+ * Capability discovery: registers into the compat layer's capability registry
+ * when that service is present, so other plugins can find this API instead of
+ * hard-depending on this package.
+ */
+import z from '@deepseek-ai/schemastery'
+import { randomUUID } from 'node:crypto'
+import { Service } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+/** One subagent memory entry. */
+const MemoryEntrySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  content: z.string(),
+  tags: z.array(z.string()),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  /** Durable session id of the subagent this entry belongs to. */
+  ownerSession: z.string(),
+  /** 'subagent' (its own tool call) | 'parent' (service API) | 'user'. */
+  origin: z.string().default('subagent'),
+})
+
+/** Compact digest bound for prompt injection. */
+const SUMMARY_LIMIT = 4000
+
+export default class AgentMemory extends Service {
+  static inject = ['tools']
+
+  static Config = z.object({
+    memories: z.array(MemoryEntrySchema).default([]).volatile(),
+  })
+
+  constructor(ctx, config) {
+    super(ctx, 'agentMemory')
+    this._ctx = ctx
+    this._config = config
+    this._settings = ctx.get('settings')
+
+    // Store access mirrors media-input: through the settings pipeline the
+    // volatile field is a live read ref (writes go through settings.update);
+    // a plain loader config falls back to an in-process shadow array.
+    const raw = config?.memories
+    if (this._settings !== undefined) {
+      this._memories = raw && typeof raw.get === 'function' ? raw : { get: () => (Array.isArray(raw) ? raw : []) }
+      this._shadowWrite = undefined
+    } else {
+      let shadow = Array.isArray(raw) ? raw : []
+      this._memories = { get: () => shadow }
+      this._shadowWrite = (next) => { shadow = next }
+    }
+
+    this._registerTools(ctx)
+    ctx.effect(() => ctx.on('subagent/end', (info) => this._cascadeDelete(info)), 'agent-memory.cascadeDelete')
+
+    // Capability discovery through the compat layer (optional).
+    ctx.inject(['compat'], (scoped) => {
+      const registry = scoped.compat?.capabilities
+      if (registry === undefined) return
+      ctx.effect(() => registry.register({
+        name: 'agentMemory',
+        version: 2,
+        description: 'Subagent-scoped memory: read/write/summarize one child session\'s own notes, adjacency-checked.',
+        methods: ['read', 'write', 'summary'],
+      }), 'agent-memory.capability')
+    })
+  }
+
+  /** Live read of the whole store. */
+  _readAll() {
+    const value = this._memories.get()
+    return Array.isArray(value) ? value : []
+  }
+
+  /** Whole-store write: persistent via settings, else the in-process shadow. */
+  async _writeAll(memories) {
+    if (this._settings !== undefined) {
+      await this._settings.update('agent-memory', { memories })
+      return
+    }
+    this._shadowWrite(memories)
+  }
+
+  /**
+   * Adjacency check for the service API: the caller may touch only a child it
+   * parents (or itself). Unknown/dead sessions are refused.
+   * @param {string} targetSessionId
+   * @param {string} callerSessionId
+   */
+  _assertAdjacent(targetSessionId, callerSessionId) {
+    if (typeof targetSessionId !== 'string' || targetSessionId === '') {
+      throw new Error('agent-memory: a target session id is required')
+    }
+    if (typeof callerSessionId !== 'string' || callerSessionId === '') {
+      throw new Error('agent-memory: a caller session id is required (API is adjacency-checked)')
+    }
+    if (targetSessionId === callerSessionId) return
+    const sessions = this._ctx.get('sessions')
+    if (sessions === undefined) {
+      throw new Error('agent-memory: session storage is unavailable; adjacency cannot be verified')
+    }
+    const child = sessions.get(targetSessionId)
+    if (child === undefined) {
+      throw new Error(`agent-memory: session "${targetSessionId}" is not materialized; refusing access`)
+    }
+    if (child.header?.parentSession !== callerSessionId) {
+      throw new Error(`agent-memory: session "${targetSessionId}" is not your direct subagent`)
+    }
+  }
+
+  /* ------------------------------------------------------------------ *
+   * Service API (active use by the parent / other host plugins)
+   * ------------------------------------------------------------------ */
+
+  /**
+   * Read one subagent's memory entries.
+   * @param {string} childSessionId - the child whose notes are read.
+   * @param {string} callerSessionId - the delegating caller (adjacency-checked).
+   * @param {{ tag?: string }} [filter]
+   */
+  read(childSessionId, callerSessionId, filter) {
+    this._assertAdjacent(childSessionId, callerSessionId)
+    const tag = filter?.tag
+    return this._readAll()
+      .filter((entry) => entry.ownerSession === childSessionId)
+      .filter((entry) => tag === undefined || entry.tags.includes(tag))
+      .map((entry) => ({ ...entry, tags: [...entry.tags] }))
+  }
+
+  /**
+   * Write one memory entry into a subagent's own store.
+   * @param {string} childSessionId
+   * @param {string} callerSessionId
+   * @param {{ title: string, content: string, tags?: string[], origin?: string }} entry
+   * @returns {Promise<object>} the stored entry.
+   */
+  async write(childSessionId, callerSessionId, entry) {
+    this._assertAdjacent(childSessionId, callerSessionId)
+    const title = String(entry?.title ?? '').trim()
+    if (title === '') throw new Error('agent-memory: an entry title is required')
+    const now = Date.now()
+    const record = {
+      id: randomUUID(),
+      title,
+      content: String(entry?.content ?? ''),
+      tags: (entry?.tags ?? []).map((tag) => String(tag)),
+      createdAt: now,
+      updatedAt: now,
+      ownerSession: childSessionId,
+      origin: callerSessionId === childSessionId ? 'subagent' : (entry?.origin ?? 'parent'),
+    }
+    await this._writeAll([...this._readAll(), record])
+    return record
+  }
+
+  /**
+   * A compact text digest of one subagent's memory, ready for prompt
+   * injection by the delegating side.
+   * @param {string} childSessionId
+   * @param {string} callerSessionId
+   * @returns {string} '' when the child has no memory.
+   */
+  summary(childSessionId, callerSessionId) {
+    const entries = this.read(childSessionId, callerSessionId)
+    if (entries.length === 0) return ''
+    const lines = [`Subagent memory (${entries.length}):`]
+    for (const entry of entries) {
+      const tags = entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : ''
+      lines.push(`- ${entry.title}${tags}: ${entry.content}`)
+    }
+    const text = lines.join('\n')
+    return text.length > SUMMARY_LIMIT ? `${text.slice(0, SUMMARY_LIMIT)}…` : text
+  }
+
+  /* ------------------------------------------------------------------ *
+   * Tools (passive use by the subagent itself)
+   * ------------------------------------------------------------------ */
+
+  _registerTools(ctx) {
+    ctx.tools.register(defineTool({
+      name: 'memory_add',
+      description: 'Remember one note in YOUR OWN memory (this session only). Use it for findings, decisions, and context worth carrying across your steps.',
+      parameters: {
+        title: { type: 'string', required: true, description: 'Short title.' },
+        content: { type: 'string', required: true, description: 'The note body.' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags for retrieval.' },
+      },
+      output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: `remembered: ${v.title} (${v.id})` }] },
+      execute: async (args, exec) => {
+        const sessionId = exec.agent?.session?.header?.id
+        if (sessionId === undefined) throw new Error('this tool requires a session')
+        const now = Date.now()
+        const record = {
+          id: randomUUID(),
+          title: String(args.title),
+          content: String(args.content),
+          tags: (args.tags ?? []).map((tag) => String(tag)),
+          createdAt: now,
+          updatedAt: now,
+          ownerSession: sessionId,
+          origin: 'subagent',
+        }
+        await this._writeAll([...this._readAll(), record])
+        return record
+      },
+    }))
+
+    ctx.tools.register(defineTool({
+      name: 'memory_list',
+      description: 'List the notes in YOUR OWN memory (this session only).',
+      parameters: { tag: { type: 'string', description: 'Optional tag filter.' } },
+      output: {
+        schema: { type: 'json' },
+        render: (_a, v) => [{
+          type: 'text',
+          text: Array.isArray(v) && v.length
+            ? v.map((m) => `- ${m.title} (${m.id}) [${m.contentLength} chars]${m.tags.length ? ` [${m.tags.join(', ')}]` : ''}`).join('\n')
+            : '(no memories)',
+        }],
+      },
+      execute: async (args, exec) => {
+        const sessionId = exec.agent?.session?.header?.id
+        if (sessionId === undefined) throw new Error('this tool requires a session')
+        const tag = args.tag === undefined || args.tag === '' ? undefined : String(args.tag)
+        return this._readAll()
+          .filter((entry) => entry.ownerSession === sessionId)
+          .filter((entry) => tag === undefined || entry.tags.includes(tag))
+          .map((entry) => ({
+            id: entry.id,
+            title: entry.title,
+            tags: [...entry.tags],
+            contentLength: String(entry.content).length,
+            createdAt: entry.createdAt,
+            updatedAt: entry.updatedAt,
+          }))
+      },
+    }))
+
+    ctx.tools.register(defineTool({
+      name: 'memory_get',
+      description: 'Read one note from YOUR OWN memory by id.',
+      parameters: { id: { type: 'string', required: true } },
+      output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: v === null ? 'not found' : `${v.title}\n${v.content}` }] },
+      execute: async (args, exec) => {
+        const sessionId = exec.agent?.session?.header?.id
+        if (sessionId === undefined) throw new Error('this tool requires a session')
+        const found = this._readAll().find((entry) => entry.id === String(args.id) && entry.ownerSession === sessionId)
+        return found === undefined ? null : { ...found, tags: [...found.tags] }
+      },
+    }))
+  }
+
+  /** Cascade-delete a settled subagent's memory. */
+  async _cascadeDelete(info) {
+    if (info === undefined || info.id === undefined) return
+    const arr = this._readAll()
+    const next = arr.filter((entry) => entry.ownerSession !== info.id)
+    if (next.length !== arr.length) await this._writeAll(next)
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "dsh-subagent-memory",
+  "description": "Subagent-scoped memory for DeepSeek Harness: memory_add/list/get tools for a delegated child's own notes, a cascade delete when the child settles, and an adjacency-checked service API (ctx.agentMemory read/write/summary) for the delegating parent or other host plugins. No global store, no browser page - one narrow responsibility.",
+  "version": "0.2.0",
+  "author": "jd962",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "icon": "./icon.svg",
+  "engines": {
+    "node": ">=24",
+    "dsh": "0.2.0-rc.2"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-settings": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}