@deepmaid/maid-memory-local 0.1.0-alpha.1 → 0.1.0-alpha.2

package/lib/index.d.ts

@@ -0,0 +1,125 @@
+//#region ../maid-memory/src/types.d.ts
+interface ProviderCapabilities {
+  readonly forget: boolean;
+  readonly sharedScopes: boolean;
+  readonly supportsRecent: boolean;
+}
+type ProviderStatus = 'cold' | 'ready' | 'degraded';
+/**
+ * 召回命中(M3b 任务 9 扩):scope/provenanceKind 透传 SLM 读面回显(docs/mslm-provenance-需求书
+ * §7 R4:'scope'/'provenance_kind' 两键,additive;缺席 = 个人记忆,渲染层按 scope==='global'
+ * 分流「背景事实」小节,不依赖 provenanceKind 做行为分支(v1)。
+ */
+interface RecallHit {
+  readonly id: string;
+  readonly title: string;
+  readonly content: string;
+  readonly score: number;
+  readonly createdAt?: string;
+  readonly scope?: string;
+  readonly provenanceKind?: string;
+}
+/**
+ * 读通道滤镜参数(M3b 任务 9,任务 5 裁定移交;round 1 修订回规格 §3.1 原文语义):
+ * excludeTags = tag 命中条目**降权排尾**(稳定排序,不剔除——「命中集不做硬删」),与任务 6
+ * 降级链「自队尾向前逐命中降档」协同 → 被降权条目先降档先出预算;preferRecentDays =
+ * createdAt 窗口内排序靠前(排序加权不过滤);组合时降权强于时窗提升。local 假件忽略之;
+ * memory_search 工具面不走本通道。
+ */
+interface RecallOpts {
+  readonly excludeTags?: readonly string[];
+  readonly preferRecentDays?: number;
+}
+interface RecentMemory {
+  readonly id: string;
+  readonly title: string;
+  readonly content: string;
+  readonly createdAt?: string;
+}
+/**
+ * 策展扫描条目(M3b 任务 10,三闸门之策展修订服务面):provider.scanUnsorted 的浅投影。
+ * scope/provenanceKind 词表语义同 RecallHit 回显(docs/mslm-provenance-需求书 §7:'world'/
+ * 'private'/'curated'/'legacy');扫描集固定 scope='global' 且未标注(provenance_kind=null),
+ * 故 provenanceKind 通常缺席——字段保留只为容读面回显毛边,不承担行为分支。
+ */
+interface CuratorFact {
+  readonly id: string;
+  readonly content: string;
+  readonly scope: string;
+  readonly provenanceKind?: string;
+}
+interface MemoryRecord {
+  readonly title: string;
+  readonly content: string;
+  readonly tags: readonly string[];
+  readonly importance: number;
+}
+/**
+ * 写入门 opts(M3b 任务 8,规格 §3 闸门 1):scope=global 只在守卫放行后出现(降级路径/缺省
+ * 均 personal);provenanceKind 用 SLM 落地版受控词表(docs/mslm-provenance-需求书 §7:
+ * 'world'/'private'/'curated'/'legacy',非需求书原文的 world-fact/maid-private)。
+ */
+interface WriteOpts {
+  readonly scope?: 'personal' | 'global';
+  readonly provenanceKind?: 'world' | 'private' | 'curated' | 'legacy';
+}
+interface WriteReceipt {
+  readonly id: string;
+  readonly deduped: boolean;
+  readonly scope?: string;
+}
+/**
+ * 原位修订 opts(M3b 任务 11,闸门三策展执行):键缺席 = 不变(fork update_memory 落地版
+ * 语义,docs/mslm-provenance-需求书 §7);scope/标注类修订 in-place(fact_id 不变迁);
+ * content 修订走 correction 链(fact_id 会变迁),仅确需改写正文时携带,语义调用方自担。
+ * MCP 面不能清标注、不能迁 scope='shared'(清标注走 daemon HTTP 预留面),故本面无
+ * provenanceKind:null 形态、shared 迁移不经此。
+ */
+interface UpdateOpts {
+  readonly scope?: 'personal' | 'shared' | 'global';
+  readonly provenanceKind?: 'world' | 'private' | 'curated' | 'legacy';
+  readonly content?: string;
+}
+interface MaidMemoryProvider {
+  readonly id: string;
+  readonly capabilities: ProviderCapabilities;
+  status(): Promise<ProviderStatus>;
+  recall(ns: string, query: string, limit: number, opts?: RecallOpts): Promise<RecallHit[]>;
+  write(ns: string, records: MemoryRecord[], opts?: WriteOpts): Promise<WriteReceipt[]>;
+  forget?(ns: string, recordId: string): Promise<void>;
+  recent?(ns: string, limit: number): Promise<RecentMemory[]>;
+  /**
+   * 原位修订(M3b 任务 11):按 factId 精确修订既有事实的 scope/标注(/正文)。可选 =
+   * 能力声明(方法在场即能力,照 scanUnsorted 先例,不设独立 capabilities 位);缺席时
+   * 策展执行方逐条记错误不中断。mslm 实现 = MCP update_memory(remember 路由同款
+   * per-request profile_id 穿透);local 假件 = 内存态合成集同步。
+   */
+  update?(ns: string, factId: string, opts: UpdateOpts): Promise<void>;
+  /**
+   * 策展扫描(M3b 任务 10):该命名空间 scope='global' 且未标注(provenance_kind=null)的
+   * 待分拣集。可选 = 能力声明(方法在场即能力,不设独立 capabilities 位——策展是低频管理
+   * 面不是读写主路);缺席时调用方按 [] 优雅降级,不视作故障。mslm 实现 = MCP list_recent
+   * 策展筛选参数(fork 落地);local 假件 = 合成 canned 集。
+   */
+  scanUnsorted?(ns: string): Promise<CuratorFact[]>;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/index.d.ts
+declare const name = "maid-memory-local";
+declare const inject: string[];
+/**
+ * 策展扫描合成集(M3b 任务 10,铁律 7:只用 Doris/合成内容):global+null / global+已标注 /
+ * personal 混排的 canned 假件集,scanUnsorted 只回 global+null 子集(与 mslm 服务端显式筛选
+ * 同语义)。导出供契约测试推导期望集;ns 无关(local 是降级假件,无真实 global 层可盘)。
+ */
+declare const SYNTHETIC_UNSORTED_SCAN: readonly CuratorFact[];
+declare const apply: (ctx: any, config?: {
+  dataFile?: string;
+}) => void;
+/** local 降级假件:自包含 JSONL + 内存关键词打分(规格 §7.1;有意保持简单,不做向量/BM25)。 */
+declare function createLocalMemoryProvider(config: {
+  dataFile: string;
+}): MaidMemoryProvider;
+//#endregion
+export { SYNTHETIC_UNSORTED_SCAN, apply, createLocalMemoryProvider, inject, name };

package/lib/index.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { managedPathsOf } from "@deepmaid/maid-identity/managed-paths";
 //#region src/index.ts
 const name = "maid-memory-local";
 const inject = ["maidMemory"];
@@ -32,9 +33,10 @@ const SYNTHETIC_UNSORTED_SCAN = [
 		scope: "personal"
 	}
 ];
-const apply = (ctx, config) => {
-	if (!config?.dataFile) throw new Error("maid-memory-local: config.dataFile 必填");
-	ctx.maidMemory.registerProvider(createLocalMemoryProvider(config));
+const apply = (ctx, config = {}) => {
+	if (ctx.maidMemory?.hasBuiltInProvider?.("local") === true) return;
+	const dataFile = config.dataFile ?? managedPathsOf(ctx).memoryFile;
+	ctx.maidMemory.registerProvider(createLocalMemoryProvider({ dataFile }));
 };
 function tokenize(text) {
 	const lower = text.toLowerCase();

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@deepmaid/maid-memory-local",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
-    ".": "./lib/index.js"
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
   },
   "files": [
     "lib"
   ],
+  "dependencies": {
+    "@deepmaid/maid-identity": "0.1.0-alpha.2"
+  },
   "devDependencies": {
     "tsdown": "0.22.14",
     "typescript": "6.0.3"