sage-mem 0.8.0 → 0.9.0

package/lib/typert.host.js

@@ -25,6 +25,11 @@ const starmapStarSchema = z.object({
 	'desc': z.string().readonly(),
 	'bytes': z.number().readonly(),
 	'mtimeMs': z.number().readonly(),
+	// 归档星：`archived` 每颗星都有（活动星是 false）；两个留痕字段只对归档星出现，
+	// 且旧版 autodream 工具归档的文件没有它们 —— 所以 optional，不是 nullable。
+	'archived': z.boolean().readonly(),
+	'archivedAt': z.string().readonly().optional(),
+	'archivedReason': z.string().readonly().optional(),
 }).readonly()
 const starmapListSchema = z.object({
 	'count': z.number().readonly(),
@@ -63,6 +68,152 @@ const deleteResultSchema = z.object({
 	'error': z.string().readonly().optional(),
 }).readonly()
 
+// ── 归档区（v0.9.0 档案馆）─────────────────────────────────────────────────
+// 归档条目的形状 = fileSchema + 两个留痕字段。留痕可能为空串（旧版 autodream 工具
+// 直接移文件、不写留痕），所以是 string 而不是 optional —— 面板永远能拿到一个值。
+const archivedFileSchema = z.object({
+	'file': z.string().readonly(),
+	'type': z.string().readonly(),
+	'description': z.string().readonly(),
+	'size': z.number().readonly(),
+	'tags': z.array(z.string()).readonly(),
+	'archivedAt': z.string().readonly(),
+	'archivedReason': z.string().readonly(),
+}).readonly()
+const archivedListSchema = z.object({
+	'count': z.number().readonly(),
+	'files': z.array(archivedFileSchema).readonly(),
+}).readonly()
+
+// 归档缘由：用户输入的一句话。真正的 YAML 转义在 host 侧 yamlScalar（值里的「: 」「 #」），
+// 这里只兜长度 —— 缘由不该长到把 frontmatter 变成正文。
+const archiveReasonSchema = z.string().max(1000).optional()
+// starmap.listStars 的可选开关：不看归档星时行为与从前完全一致。
+const includeArchivedSchema = z.boolean().optional()
+
+// 归档 / 恢复的结果：成功 `{ ok: true, file }`，失败 `{ ok: false, error }` —— 失败分支
+// **没有 file**（名字本身可能就是非法的）。所以不能复用 writeResultSchema：那边 `file`
+// 是必填（writeFile 连失败都带着归一后的文件名），strict 校验会把失败分支判成坏结果。
+const archiveResultSchema = z.object({
+	'ok': z.boolean().readonly(),
+	'file': z.string().readonly().optional(),
+	'error': z.string().readonly().optional(),
+}).readonly()
+
+// 归档文件的读 / 写（v0.9.0 B1b）：归档不是删除，正文要能看能改。三个类型名与活跃记忆
+// 那套（FileName / FileContent / WriteResult）对称，只是作用目录换成 `memory/archive/`。
+// 名字仍受 safeName 约束 —— 调用方不许自己拼路径。
+const archivedReadResultSchema = z.object({
+	'name': z.string().readonly(),
+	'content': z.string().readonly(),
+}).readonly()
+// 写归档的结果与 writeResultSchema 同形，但**另立一个类型名**：strict 层要能区分
+// 「写活跃记忆」与「写归档记忆」两条路径，将来两者形状分叉时也不必回头改协议。
+const archivedWriteResultSchema = z.object({
+	'ok': z.boolean().readonly(),
+	'file': z.string().readonly(),
+	'error': z.string().readonly().optional(),
+}).readonly()
+
+// ── 面板 API（v0.9.0 D1）：体检 / 归档候选 / 设置 / 保留名原样读写 ──────────────
+// 审计报告：字段面就是 `auditMemoryDir()` 的返回，逐项在这里钉住 —— strict 会把没声明的
+// 字段剥掉，面板看到的清单必须与模型看到的一致。
+const auditItemSchema = z.object({ 'file': z.string().readonly() }).readonly()
+const auditLinkSchema = z.object({ 'file': z.string().readonly(), 'target': z.string().readonly() }).readonly()
+const auditTypeMismatchSchema = z.object({
+	'file': z.string().readonly(),
+	'type': z.string().readonly(),
+	'prefix': z.string().readonly(),
+	'effective': z.string().readonly(),
+}).readonly()
+const auditHazardSchema = z.object({ 'file': z.string().readonly(), 'line': z.string().readonly() }).readonly()
+const auditReportSchema = z.object({
+	'dir': z.string().readonly(),
+	'fileCount': z.number().readonly(),
+	'skipped': z.number().readonly(),
+	'archivedCount': z.number().readonly(),
+	'indexEntries': z.number().readonly(),
+	'dangling': z.array(auditItemSchema).readonly(),
+	'unlisted': z.array(auditItemSchema).readonly(),
+	'typeMismatch': z.array(auditTypeMismatchSchema).readonly(),
+	'crlf': z.array(auditItemSchema).readonly(),
+	'brokenLinks': z.array(auditLinkSchema).readonly(),
+	'archivedLinks': z.array(auditLinkSchema).readonly(),
+	'hashHazards': z.array(auditHazardSchema).readonly(),
+	'noFrontmatter': z.array(auditItemSchema).readonly(),
+	'unreadable': z.array(auditItemSchema).readonly(),
+	'problems': z.number().readonly(),
+}).readonly()
+
+const archiveCandidateSchema = z.object({
+	'file': z.string().readonly(),
+	'type': z.string().readonly(),
+	'days': z.number().readonly(),
+	'limit': z.number().readonly(),
+	'reason': z.string().readonly(),
+}).readonly()
+const archiveCandidatesResultSchema = z.object({
+	'count': z.number().readonly(),
+	'candidates': z.array(archiveCandidateSchema).readonly(),
+	'autoArchive': z.string().readonly(),
+	'thresholds': z.object({
+		'project': z.number().readonly(),
+		'reference': z.number().readonly(),
+		'user': z.number().readonly(),
+	}).readonly(),
+}).readonly()
+
+// 设置：limits = 当前**已生效**的值（模块加载时读的），pendingLimits = 待生效值
+// （settings.json > 环境变量 > 默认）。两个都给，界面才说得清「改了要重启」。
+const settingsLimitsSchema = z.object({
+	'maxResults': z.number().readonly(),
+	'maxChars': z.number().readonly(),
+	'maxBaseline': z.number().readonly(),
+	'maxSessionBytes': z.number().readonly(),
+	'staleDays': z.number().readonly(),
+}).readonly()
+const settingsSchema = z.object({
+	'limits': settingsLimitsSchema,
+	'pendingLimits': settingsLimitsSchema,
+	'restartRequired': z.boolean().readonly(),
+	'reserved': z.array(z.string()).readonly(),
+	'reservedExtra': z.array(z.string()).readonly(),
+}).readonly()
+const settingsPatchSchema = z.object({
+	'limits': z.object({
+		'maxResults': z.number().optional(),
+		'maxChars': z.number().optional(),
+		'maxBaseline': z.number().optional(),
+		'maxSessionBytes': z.number().optional(),
+		'staleDays': z.number().optional(),
+	}).readonly().optional(),
+	'reserved': z.array(z.string()).optional(),
+}).readonly()
+// 成功回 { ok, settings, restartRequired }，失败回 { ok:false, error } —— 两条分支并集。
+const settingsResultSchema = z.object({
+	'ok': z.boolean().readonly(),
+	'error': z.string().readonly().optional(),
+	'settings': settingsSchema.optional(),
+	'restartRequired': z.boolean().readonly().optional(),
+}).readonly()
+
+// 保留名原样读写。读的两条分支（成功 {name,content} / 拒绝 {ok:false,error}）用可选字段
+// 的并集接住；写的失败分支可能没有 file，所以 file 也是 optional。
+const rawReadResultSchema = z.object({
+	'name': z.string().readonly().optional(),
+	'content': z.string().readonly().optional(),
+	'ok': z.boolean().readonly().optional(),
+	'error': z.string().readonly().optional(),
+}).readonly()
+const rawWriteResultSchema = z.object({
+	'ok': z.boolean().readonly(),
+	'file': z.string().readonly().optional(),
+	'error': z.string().readonly().optional(),
+}).readonly()
+// 保留名的体积上限比单条记忆大得多（session-log.md 天然 > 512 KB）—— 4 MB，独立于
+// fileContentSchema，别把两者混用。
+const rawFileContentSchema = z.string().max(4 * 1024 * 1024)
+
 // ── autodream（夜间记忆整理）───────────────────────────────────────────────
 // 配置的每一项都可写；lastResult 是一个「成功/失败两条分支共用」的结构，
 // 所以除了三个必有字段外全是 optional —— 用 strict 校验两种形态的并集，
@@ -303,13 +454,148 @@ export const TYPERT = {
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#DeleteResult', schema: deleteResultSchema, create: () => deleteResultSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 		},
+		{
+			id: 'sage-mem#memory/archive',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'archive',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#FileName', schema: fileNameSchema, create: () => fileNameSchema } },
+				{ name: 'reason', wire: 'reason', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchiveReason', schema: archiveReasonSchema, create: () => archiveReasonSchema } },
+			],
+			// 归档与恢复都回「成不成、动的哪个文件」；失败分支没有 file（名字本身可能就非法），
+			// 所以用 ArchiveResult（file / error 都 optional），不能复用 file 必填的 writeResultSchema。
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchiveResult', schema: archiveResultSchema, create: () => archiveResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/restore',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'restore',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#FileName', schema: fileNameSchema, create: () => fileNameSchema } },
+			],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchiveResult', schema: archiveResultSchema, create: () => archiveResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/listArchived',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'listArchived',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedList', schema: archivedListSchema, create: () => archivedListSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/readArchived',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'readArchived',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedFileName', schema: fileNameSchema, create: () => fileNameSchema } },
+			],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedFileContent', schema: archivedReadResultSchema, create: () => archivedReadResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/writeArchived',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'writeArchived',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedFileName', schema: fileNameSchema, create: () => fileNameSchema } },
+				// 正文与「写活跃记忆」共用同一个 512 KB 上限 schema；类型名沿用 #ArchivedFileContent
+				// 是为了与「读归档」那一侧对称（活跃记忆那套也是 FileContent 一符两用）。
+				{ name: 'content', wire: 'content', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedFileContent', schema: fileContentSchema, create: () => fileContentSchema } },
+			],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchivedWriteResult', schema: archivedWriteResultSchema, create: () => archivedWriteResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/audit',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'audit',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#AuditReport', schema: auditReportSchema, create: () => auditReportSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/archiveCandidates',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'archiveCandidates',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#ArchiveCandidates', schema: archiveCandidatesResultSchema, create: () => archiveCandidatesResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/getSettings',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'getSettings',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#MemorySettings', schema: settingsSchema, create: () => settingsSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/setSettings',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'setSettings',
+			invocation: { kind: 'direct' },
+			parameters: [
+				// 补丁式：面板一次只改一项时不该把没碰过的字段用旧值覆盖回去。
+				{ name: 'patch', wire: 'patch', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#MemorySettingsPatch', schema: settingsPatchSchema, create: () => settingsPatchSchema } },
+			],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#MemorySettingsResult', schema: settingsResultSchema, create: () => settingsResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/readRaw',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'readRaw',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ReservedFileName', schema: fileNameSchema, create: () => fileNameSchema } },
+			],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#RawFileContent', schema: rawReadResultSchema, create: () => rawReadResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
+		{
+			id: 'sage-mem#memory/writeRaw',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'writeRaw',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{ name: 'name', wire: 'name', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#ReservedFileName', schema: fileNameSchema, create: () => fileNameSchema } },
+				// 4 MB：与 fileContentSchema（512 KB）**不是同一个上限**，见 rawFileContentSchema 的注释。
+				{ name: 'content', wire: 'content', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#RawFileContent', schema: rawFileContentSchema, create: () => rawFileContentSchema } },
+			],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#RawWriteResult', schema: rawWriteResultSchema, create: () => rawWriteResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
 		{
 			id: 'sage-mem#starmap/listStars',
 			service: 'starmap',
 			namespace: 'starmap',
 			method: 'listStars',
 			invocation: { kind: 'direct' },
-			parameters: [],
+			parameters: [
+				{ name: 'includeArchived', wire: 'includeArchived', source: 'json', codec: { mode: 'strict', typeSymbol: 'sage-mem/types#StarmapIncludeArchived', schema: includeArchivedSchema, create: () => includeArchivedSchema } },
+			],
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#StarmapList', schema: starmapListSchema, create: () => starmapListSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 		},

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "File-based memory plugin for DeepSeek Harness (DSH) — cross-session memory in plain markdown files, with a memory star-map view, type/tag filtering, retrieval aliases, and an optional autodream pass that consolidates memories on demand or on a schedule — with per-run rollback points, a per-file change declaration (what changed and why), and a separately selectable model for the consolidation pass",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -87,6 +87,8 @@
     "claude-code"
   ],
   "scripts": {
-    "test": "node test/run.mjs"
+    "test": "node test/run.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "images": "node scripts/make-readme-images.mjs"
   }
 }