@max-null/dsh-memory 0.19.1 → 0.20.0

package/README.md

@@ -76,6 +76,18 @@ npm install @max-null/dsh-memory
 
 两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。旧版双重前缀文件名（`memory_project_memory_project_<hash>.json`）在打开时自动迁移为规范名。
 
+## 主题（topic，0.20.0）
+
+`namespace` 管「在哪生效」，`topic` 管「这条讲什么」，两者正交：
+
+| 字段 | 回答的问题 | 取值 |
+|---|---|---|
+| `namespace` | 换个项目还成立吗 | `global` / `project` |
+| `kind` | 是记忆还是提示词模板 | `fact` / `prompt` |
+| `topic` | 这条记忆讲什么 | 自由字符串：`见闻` / `约定` / `坑` / `偏好` / `事实` / `判据` … |
+
+`memory_save` 传 `topic` 落库，`memory_list` / `memory_search` 传 `topic` 切片。留空或省略即「未分类」。用它把「自己出去逛到的」（`见闻`）和「一起干活时记下的」分开翻，不必再往正文里手写前缀。
+
 ## 跨工作区可见性（0.10.0 / 0.11.0）
 
 project 记忆按**会话工作区**分文件存放，所以「工作区」就是可见性的边界。0.10.0 起补了三个方向——针对的是同一个盲区：**不知道存在**（检索是有意图的动作，搜不出自己不知道存在的东西）。

package/dist/engine.d.ts

@@ -81,6 +81,13 @@ export interface MemoryRecord {
     lastUsedAt?: number;
     /** 记录类别（缺省 'fact'）。 */
     kind?: MemoryKind;
+    /**
+     * 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …
+     *
+     * 与 `kind` 正交：`kind` 分「记忆还是提示词模板」，`topic` 分「这条记忆讲什么」。
+     * 存自由字符串，方便「只翻我出去逛到的那些」这类切片。
+     */
+    topic?: string;
     /** prompt 记录元数据（仅 kind==='prompt'）。 */
     meta?: PromptMetaIndex;
     /**
@@ -93,6 +100,8 @@ export interface MemoryWrite {
     content: string;
     namespace?: MemoryNamespace;
     keywords?: string[];
+    /** 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …；省略表示未分类。 */
+    topic?: string;
     /** 写入来源（2026-09-15）；缺省 'agent'（主模型写入）。面板等人工路径传 'human'。 */
     source?: MemorySource;
     /**
@@ -115,6 +124,8 @@ export interface MemoryFilter {
     quarantined?: boolean;
     /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
     kind?: MemoryKind;
+    /** 主题过滤（0.20.0）：只取这个 topic 的记录；缺省不过滤。 */
+    topic?: string;
     /**
      * 更新时间下界 / 上界（0.12.0；epoch ms，含端点）。
      *

package/dist/engine.js

@@ -145,10 +145,11 @@ function toRecord(id, block) {
         ...block.stale === undefined ? {} : { stale: block.stale },
         ...block.staleReason === undefined ? {} : { staleReason: block.staleReason },
     };
-    // 0.6.0 模板库字段（缺省 fact；prompt 元数据透传）
+    // 0.6.0 模板库字段（缺省 fact；prompt 元数据透传）；0.20.0 起带主题
     return {
         ...base,
         ...block.kind === undefined ? {} : { kind: block.kind },
+        ...block.topic === undefined ? {} : { topic: block.topic },
         ...block.meta === undefined ? {} : { meta: block.meta },
     };
 }
@@ -758,6 +759,8 @@ export class MemoryEngine extends Service {
             ...input.injected === undefined ? {} : { injectedAuto: false },
             // 有效性锚点（可选）：值变了这条记忆会被标 stale，不再被当成仍然正确
             ...input.anchor === undefined ? {} : { anchor: input.anchor },
+            // 主题（0.20.0）：省略即未分类，与 `kind`（fact/prompt）正交
+            ...input.topic === undefined || input.topic.trim() === '' ? {} : { topic: input.topic.trim() },
             ...verdict.quarantined
                 ? { quarantined: true, ...verdict.reason === undefined ? {} : { quarantineReason: verdict.reason } }
                 : {},
@@ -778,7 +781,8 @@ export class MemoryEngine extends Service {
             // 0.12.0：按更新时间筛——与注入排序、注入行的日期标记同一个依据，不制造第二个「新」的定义
             && (filter?.after === undefined || record.updatedAt >= filter.after)
             && (filter?.before === undefined || record.updatedAt <= filter.before)
-            && (filter?.kind === undefined || (record.kind ?? 'fact') === filter.kind));
+            && (filter?.kind === undefined || (record.kind ?? 'fact') === filter.kind)
+            && (filter?.topic === undefined || record.topic === filter.topic));
     }
     /**
      * 关键词检索。每次成功返回的检索都记一条查询日志（⑥ 2026-09-15）——命中与否都记：

package/dist/index.js

@@ -125,6 +125,7 @@ const RECORD_SCHEMA = {
         injected: { type: 'boolean', required: true },
         content: { type: 'string', required: true },
         keywords: { type: 'array', required: true, items: { type: 'string' } },
+        topic: { type: 'string', description: '主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …；缺省表示未分类。' },
         createdAt: { type: 'number', required: true },
         updatedAt: { type: 'number', required: true },
         lastUsedAt: { type: 'number' },
@@ -296,6 +297,7 @@ function recordValue(record) {
         injected: record.injected,
         content: record.content,
         keywords: record.keywords,
+        ...record.topic === undefined ? {} : { topic: record.topic },
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         ...record.lastUsedAt === undefined ? {} : { lastUsedAt: record.lastUsedAt },
@@ -587,6 +589,7 @@ export async function apply(ctx, config) {
             content: { type: 'string', required: true, description: 'Plaintext memory content.' },
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Where it applies; defaults to global.' },
             keywords: { type: 'array', items: { type: 'string' }, description: 'Explicit searchable anchors for memory_search. Give several angles (synonyms, abbreviations, zh/en) or it will not be found later. 多角度关键词（同义词、缩写、中英），否则将来检索不到它。' },
+            topic: { type: 'string', description: 'What this memory is about, one short word: 见闻 (things noticed while wandering) / 约定 (standing agreement) / 坑 (a pitfall hit) / 偏好 (a preference) / 事实 / 判据. Orthogonal to namespace. 主题：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据；与 namespace 正交，缺省表示未分类。' },
             injected: { type: 'boolean', description: 'Set true to make this memory resident in every turn\'s context, as a deliberate decision that no longer auto-expires. Reserve it for rules, standing agreements and judgement criteria — the kind that must apply even when nobody thinks to search for them. Facts, references and case notes stay search-only (omit it). 设为 true 让这条记忆每轮常驻上下文，且视为有意决定、不再被自动淘汰。只用于规则、长期约定与判据——那些「没人想起来搜也必须生效」的记忆；事实、参考与案例留作按需检索（省略即可）。' },
             anchor: {
                 type: 'object',
@@ -609,6 +612,7 @@ export async function apply(ctx, config) {
                 content: args.content,
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
+                ...args.topic === undefined ? {} : { topic: args.topic },
                 ...args.injected === undefined ? {} : { injected: args.injected },
                 // 参数已由 tool schema 校验，这里的窄化只为过类型
                 ...args.anchor === undefined
@@ -632,6 +636,7 @@ export async function apply(ctx, config) {
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态（suggested=待审核 / approved=已审核）.' },
             injected: { type: 'boolean', description: 'Restrict by the persistent-injection switch. 按常驻注入开关过滤.' },
+            topic: { type: 'string', description: 'Restrict to one topic (见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …). 按主题过滤（0.20.0）.' },
             after: { type: 'string', description: 'Only memories updated at/after this time: `YYYY-MM-DD`, or a relative form like `7d` / `30d`. 只返回此后更新过的记忆（`YYYY-MM-DD`，或相对形式 `7d` / `30d`）.' },
             before: { type: 'string', description: 'Only memories updated at/before this time (same forms as `after`). 只返回此前更新过的记忆（写法同 after）.' },
         },
@@ -647,6 +652,7 @@ export async function apply(ctx, config) {
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.injected === undefined ? {} : { injected: args.injected },
+                ...args.topic === undefined ? {} : { topic: args.topic },
                 ...after === undefined ? {} : { after },
                 ...before === undefined ? {} : { before },
             }, execProjectCwd(exec)).then(records => records.map(recordValue));
@@ -661,6 +667,7 @@ export async function apply(ctx, config) {
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态.' },
             kind: { type: 'string', enum: ['fact', 'prompt'], description: 'Restrict by record kind — fact (memories, default) or prompt (templates; use prompt_search instead). 按记录类别过滤：fact=记忆（默认）/ prompt=模板（模板请用 prompt_search）.' },
+            topic: { type: 'string', description: 'Restrict to one topic (见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …). 按主题过滤（0.20.0）.' },
             limit: { type: 'integer', default: DEFAULT_SEARCH_LIMIT, description: 'Maximum hits to return (default 20; 0 = no limit; negative falls back to 20). 最多返回条数（默认 20；0 = 不限；负数按 20）.' },
         },
         output: {
@@ -676,6 +683,7 @@ export async function apply(ctx, config) {
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.kind === undefined ? {} : { kind: args.kind },
+                ...args.topic === undefined ? {} : { topic: args.topic },
             }, execProjectCwd(exec)).then(hits => (limit === 0 ? hits : hits.slice(0, limit)).map(hitValue));
         },
         presentCall: args => present('Search memory', 'read', args.query),

package/dist/schema.d.ts

@@ -63,6 +63,7 @@ export declare const blockSchema: z.ZodObject<{
         fact: "fact";
         prompt: "prompt";
     }>>;
+    topic: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodObject<{
         seq: z.ZodOptional<z.ZodNumber>;
         name: z.ZodString;

package/dist/schema.js

@@ -45,6 +45,14 @@ export const blockSchema = z.object({
     lastUsedAt: z.number().optional(),
     vector: z.array(z.number()).optional(),
     kind: z.enum(['fact', 'prompt']).optional(),
+    /**
+     * 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 … 自由字符串。
+     *
+     * 与 `kind` 正交——`kind` 分「记忆还是提示词模板」（记录类别），`topic` 分「这条记忆讲什么」
+     * （内容主题）。用自由字符串而不是枚举：新增主题不该要求改 schema，而枚举一旦写死，
+     * 存量文件里出现未登记的值会被门三判成不合规、进而整块读不出来。
+     */
+    topic: z.string().optional(),
     meta: z.object({
         seq: z.number().optional(),
         name: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {