dsh-cortex-memory 0.1.0 → 0.2.0-rc.13

package/examples/README.md

@@ -0,0 +1,72 @@
+# Cortex bge 可选 profile
+
+默认 **不开启** bge。这个示例只给想要本地语义召回的人用：
+
+- 需要本地 Ollama / OpenAI-compatible embedding 服务
+- 需要 `bge-m3`（1024 维）
+- 查询延迟会明显高于 FTS
+- 没有服务时不要开；失败会退开放，不会假装成功
+
+## 一键创建独立 profile
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\examples\setup-cortex-bge.ps1 `
+  -Dsh "D:\path\to\dsh.cmd" `
+  -Profile cortex-bge `
+  -Package "C:\path\to\dsh-cortex-memory-0.1.0.tgz"
+```
+
+首次先用 Ollama 启动模型服务：
+
+```powershell
+ollama serve
+ollama pull bge-m3
+```
+
+脚本会：
+
+1. 用 DSH 的 `web` 模板新建一个空 profile
+2. 安装 cortex 包
+3. 写独立的 `dataRoot/dbFile`
+4. 写 `features.vector: true`
+5. 写 `model-config.json`（local / bge-m3 / 1024）
+
+它**不会**改 desktop，也不会自动启动服务。
+
+## 启动
+
+```powershell
+& $Dsh --profile cortex-bge --port 0 --no-open
+```
+
+打开后到 Cortex 设置里确认：
+
+```text
+embedding mode: local
+model: bge-m3
+dim: 1024
+```
+
+## 关闭
+
+移除 profile 或把 `features.vector` 改回 `false`。  
+不想用语义模型时，FTS 仍是默认路径。
+
+## 卸载 cortex
+
+`dsh plugin remove` 不会删手写 patch。用：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\examples\uninstall-cortex.ps1 `
+  -Dsh "D:\path\to\dsh.cmd" `
+  -Profile cortex-bge
+```
+
+脚本会：
+
+1. 若已安装则 `plugin remove`
+2. 只删除 `- id: cortex` 段，保留其他 patch
+3. 跑一次 `--dump-config`
+4. **不删 dataRoot**
+
+如果已经手动移除，脚本会跳过 remove，仍清理残留 patch。

package/examples/setup-cortex-bge.ps1

@@ -0,0 +1,66 @@
+[CmdletBinding()]
+param(
+  [string]$Dsh = 'dsh',
+  [string]$Profile = 'cortex-bge',
+  [string]$Package = 'dsh-cortex-memory',
+  [string]$DataRoot = (Join-Path $HOME '.dsh\cortex-bge'),
+  [string]$BaseUrl = 'http://127.0.0.1:11434/v1',
+  [string]$Model = 'bge-m3',
+  [int]$Dim = 1024
+)
+
+$ErrorActionPreference = 'Stop'
+$dshCommand = Get-Command $Dsh -ErrorAction SilentlyContinue
+if (-not $dshCommand) { throw "dsh command not found: $Dsh. Pass -Dsh with the path to dsh.cmd." }
+$dshPath = $dshCommand.Source
+$profilePath = Join-Path (Join-Path $HOME '.dsh\profiles') $Profile
+if (Test-Path $profilePath) { throw "profile already exists: $profilePath. Choose another -Profile or remove it first." }
+
+if ($Package -match '\.tgz$') {
+  $Package = (Resolve-Path $Package).Path
+}
+
+& $dshPath --profile $Profile --from-default-profile web --dump-config | Out-Null
+& $dshPath plugin --profile $Profile add $Package
+if ($LASTEXITCODE -ne 0) { throw "plugin install failed with exit code $LASTEXITCODE" }
+
+New-Item -ItemType Directory -Force -Path $DataRoot | Out-Null
+$modelConfig = [ordered]@{
+  embedding = [ordered]@{
+    mode = 'local'
+    baseUrl = $BaseUrl
+    model = $Model
+    dim = $Dim
+    apiKey = ''
+  }
+  rerank = [ordered]@{
+    enabled = $false
+    baseUrl = ''
+    model = ''
+    apiKey = ''
+  }
+}
+$utf8 = New-Object System.Text.UTF8Encoding($false)
+[System.IO.File]::WriteAllText(
+  (Join-Path $DataRoot 'model-config.json'),
+  (($modelConfig | ConvertTo-Json -Depth 5) + "`n"),
+  $utf8
+)
+
+$patchFile = Join-Path $profilePath 'cordis.patch.yml'
+$patch = @"
+# bge profile generated by examples/setup-cortex-bge.ps1
+- id: cortex
+  name: dsh-cortex
+  config:
+    dataRoot: '$($DataRoot.Replace('\','/'))'
+    dbFile: '$((Join-Path $DataRoot 'cortex.sqlite').Replace('\','/'))'
+    features:
+      vector: true
+"@
+[System.IO.File]::WriteAllText($patchFile, $patch + "`n", $utf8)
+
+Write-Host "profile: $profilePath"
+Write-Host "dataRoot: $DataRoot"
+Write-Host "Next: & '$dshPath' --profile $Profile --port 0 --no-open"
+Write-Host "Start the local embedding service first: $BaseUrl"

package/examples/uninstall-cortex.ps1

@@ -0,0 +1,91 @@
+[CmdletBinding()]
+param(
+  [string]$Dsh = 'dsh',
+  [string]$Profile = 'desktop',
+  [string]$Package = 'dsh-cortex',
+  [switch]$KeepPatch
+)
+
+$ErrorActionPreference = 'Stop'
+$dshCommand = Get-Command $Dsh -ErrorAction SilentlyContinue
+if (-not $dshCommand) { throw "dsh command not found: $Dsh. Pass -Dsh with the path to dsh.cmd." }
+$dshPath = $dshCommand.Source
+$profilePath = Join-Path (Join-Path $HOME '.dsh\profiles') $Profile
+if (-not (Test-Path $profilePath)) { throw "profile not found: $profilePath" }
+
+$packageJson = Join-Path $profilePath 'package.json'
+$installed = $false
+if (Test-Path $packageJson) {
+  try {
+    $manifest = Get-Content -LiteralPath $packageJson -Raw | ConvertFrom-Json
+    $installed = $null -ne $manifest.dependencies.$Package
+  } catch { $installed = $false }
+}
+if ($installed) {
+  & $dshPath plugin --profile $Profile remove $Package
+  if ($LASTEXITCODE -ne 0) { throw "plugin remove failed with exit code $LASTEXITCODE" }
+} else {
+  Write-Host "$Package is not installed in $Profile; skipping remove"
+}
+
+$patchFile = Join-Path $profilePath 'cordis.patch.yml'
+$configuredDataRoot = $null
+if (Test-Path $patchFile) {
+  foreach ($line in [System.IO.File]::ReadAllLines($patchFile)) {
+    if ($line -match '^\s*dataRoot:\s*(.+)$') {
+      $configuredDataRoot = $matches[1].Trim().Trim("'").Trim('"')
+      break
+    }
+  }
+}
+if (-not $configuredDataRoot) {
+  $dshHome = Join-Path $HOME '.dsh'
+  $configuredDataRoot = if ($Profile -eq 'desktop') { Join-Path $dshHome 'cortex' } else { Join-Path (Join-Path $dshHome 'cortex\profiles') $Profile }
+}
+
+if (-not $KeepPatch) {
+  if (Test-Path $patchFile) {
+    $lines = [System.IO.File]::ReadAllLines($patchFile)
+    $ranges = New-Object System.Collections.Generic.List[object]
+    $start = -1
+    for ($i = 0; $i -lt $lines.Count; $i += 1) {
+      if ($lines[$i] -match '^- ') {
+        if ($start -ge 0) { $ranges.Add([pscustomobject]@{ From = $start; To = ($i - 1) }) }
+        $start = $i
+      }
+    }
+    if ($start -ge 0) { $ranges.Add([pscustomobject]@{ From = $start; To = ($lines.Count - 1) }) }
+
+    $drop = @{}
+    foreach ($range in $ranges) {
+      $from = [int]$range.From
+      $to = [int]$range.To
+      $header = $lines[$from]
+      $body = ($lines[$from..$to] -join "`n")
+      if ($header -match '^- id:\s*cortex\s*$' -and $body -match 'name:\s*[''"]?dsh-cortex') {
+        for ($i = $from; $i -le $to; $i += 1) { $drop[$i] = $true }
+      }
+    }
+
+    if ($drop.Count -gt 0) {
+      $remaining = @()
+      for ($i = 0; $i -lt $lines.Count; $i += 1) {
+        if (-not $drop.ContainsKey($i)) { $remaining += $lines[$i] }
+      }
+      $meaningful = @($remaining | Where-Object { $_.Trim() -and -not $_.Trim().StartsWith('#') })
+      $text = if ($meaningful.Count -eq 0) { "[]`n" } else { ($remaining -join "`n") + "`n" }
+      $utf8 = New-Object System.Text.UTF8Encoding($false)
+      [System.IO.File]::WriteAllText($patchFile, $text, $utf8)
+      Write-Host "removed cortex patch block from $patchFile"
+    } else {
+      Write-Host "no cortex patch block found in $patchFile"
+    }
+  }
+
+  & $dshPath --profile $Profile --dump-config | Out-Null
+  if ($LASTEXITCODE -ne 0) { Write-Warning "dump-config still fails; inspect $profilePath\cordis.patch.yml" }
+  else { Write-Host "dump-config ok" }
+}
+
+Write-Host "profile left in place: $profilePath"
+Write-Host "cortex data was NOT deleted: $configuredDataRoot"

package/index.js

@@ -22,12 +22,18 @@ export const Config = Schema ? Schema.object({
   dataRoot: Schema.string().description('Cortex 数据目录（默认 DSH_HOME/cortex）'),
   dbFile: Schema.string().description('SQLite 文件；默认 dataRoot/cortex.sqlite'),
   scope: Schema.string().default('global').description('默认 scope'),
+  readOnlyScopes: Schema.array(Schema.string()).default([]).description('只读共享 scope 列表'),
+  scopeWriteGrants: Schema.array(Schema.any()).default([]).description('显式写授权：scope:agent 或 {grant, until}'),
   contextBudget: Schema.natural().default(2200).description('检索注入的 token 预算'),
   promptBudget: Schema.natural().default(1600).description('常驻自我/工作记忆提示词预算'),
   recallTimeoutMs: Schema.natural().default(1200).description('前台召回硬截止'),
   asyncJobs: Schema.boolean().default(true).description('允许后台任务'),
   captureSubagents: Schema.boolean().default(false).description('是否把子代理会话也写入记忆'),
   vectorEnabled: Schema.boolean().default(false).description('启用向量检索（默认用离线 hash embedder 兜底）'),
+  vectorAnnMin: Schema.natural().default(20000).description('向量 ANN 生效的最小条数'),
+  vectorAnnEngine: Schema.string().default('hnsw').description('ANN 引擎：hnsw（默认）或 nsw（旧实现）'),
+  vectorAnnEndpoint: Schema.string().default('').description('外置 ANN HTTP endpoint；空则不用外置'),
+  vectorAnnTimeoutMs: Schema.natural().default(800).description('外置 ANN 超时毫秒'),
   scheduler: Schema.boolean().default(true).description('启用宿主心跳（安全自主 tick/作业/保留计划）'),
   schedulerIntervalMs: Schema.natural().default(60000).description('心跳间隔毫秒'),
   maxCallsPerHour: Schema.natural().default(120).description('检索调用预算（宿主 prefetch 不计入）'),
@@ -48,6 +54,9 @@ export const Config = Schema ? Schema.object({
     reflect: Schema.boolean().default(true),
     growth: Schema.boolean().default(true),
     vector: Schema.boolean().default(false),
+    vectorAnn: Schema.boolean().default(false),
+    vectorAnnExternal: Schema.boolean().default(false),
+    attachmentReader: Schema.boolean().default(false),
     graph: Schema.boolean().default(true),
     llm: Schema.boolean().default(false),
     api: Schema.boolean().default(true),
@@ -109,7 +118,11 @@ export async function apply(ctx, config = {}) {
       for (const tool of createToolDefinitions(cortex)) disposers.push(ctx.tools.register(tool));
       if (runtime) disposers.push(runtime.attach(ctx));
       if (scheduler) scheduler.start();
-      if (config.features?.api !== false) disposers.push(mountApi(ctx, { cortex, logger: ctx.logger }));
+      if (config.features?.api !== false) disposers.push(mountApi(ctx, {
+        cortex,
+        logger: ctx.logger,
+        getExtractor: () => ctx.get?.('cortexExtractor') ?? null,
+      }));
       if (typeof ctx.systemPrompt?.section === 'function') {
         disposers.push(ctx.systemPrompt.section({
           name: 'cortex-self',
@@ -125,6 +138,7 @@ export async function apply(ctx, config = {}) {
           search: cortex.search,
           get: cortex.get,
           write: cortex.write,
+          ingestExtractedText: cortex.ingestExtractedText,
           self: cortex.self,
           health: cortex.health,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-cortex-memory",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.13",
   "description": "A layered, temporal, self-developing memory engine for DeepSeek Harness: working, episodic, semantic, procedural and reflective memory with hybrid retrieval, DSR forgetting, reflection, consolidation, gated self-evolution and guardian.",
   "type": "module",
   "main": "./index.js",
@@ -28,7 +28,9 @@
     "README.md",
     "docs/install-windows.md",
     "docs/models.md",
-    "docs/compatibility.md",
+    "docs/scopes.md",
+    "docs/multimodal.md",
+    "examples",
     "LICENSE"
   ],
   "scripts": {
@@ -72,14 +74,5 @@
     "self-evolving",
     "sqlite"
   ],
-  "license": "MIT",
-  "author": "dsh-cortex-memory contributors",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Lh1314-China/dsh-cortex-memory.git"
-  },
-  "homepage": "https://github.com/Lh1314-China/dsh-cortex-memory#readme",
-  "bugs": {
-    "url": "https://github.com/Lh1314-China/dsh-cortex-memory/issues"
-  }
+  "license": "MIT"
 }

package/src/adapters/markdown-import.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { hashText } from '../core/ids.js';
+import { normalizeAttachments } from '../core/attachments.js';
 
 function parseFrontmatter(text) {
   const source = String(text ?? '');
@@ -14,6 +15,10 @@ function parseFrontmatter(text) {
     const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (!match) continue;
     let value = match[2].trim();
+    if (match[1] === 'attachments') {
+      meta.attachments = value;
+      continue;
+    }
     if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
     if (value.startsWith('[') && value.endsWith(']')) value = value.slice(1, -1).split(',').map((item) => item.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
     meta[match[1]] = value;
@@ -24,6 +29,14 @@ function parseFrontmatter(text) {
 export function parseMemoryMarkdown(text) {
   const { meta, body } = parseFrontmatter(text);
   const title = meta.title || body.split(/\r?\n/).find((line) => line.startsWith('# '))?.slice(2).trim() || '未命名记忆';
+  let attachments = [];
+  if (meta.attachments) {
+    try {
+      attachments = normalizeAttachments(JSON.parse(meta.attachments));
+    } catch {
+      attachments = [];
+    }
+  }
   return {
     id: meta.id || null,
     kind: meta.kind || 'utterance',
@@ -33,6 +46,7 @@ export function parseMemoryMarkdown(text) {
     importance: Number(meta.importance ?? 0.5),
     recordedAt: meta.recorded_at || meta.date || null,
     state: meta.state || 'active',
+    attachments,
   };
 }
 
@@ -103,6 +117,7 @@ export function importMarkdown(cortex, root, { dryRun = false, scopeId = 'global
           kind: parsed.kind,
           tags: parsed.tags,
           importance: parsed.importance,
+          attachments: parsed.attachments,
           explicit: true,
           operationId: `markdown:${parsed.id ?? hashText(`${file}:${parsed.title}:${parsed.content}`)}`,
           now: parsed.recordedAt ? Date.parse(parsed.recordedAt) : undefined,
@@ -142,10 +157,12 @@ export function syncMarkdown(cortex, root, { dryRun = false, scopeId = 'global',
         if (parsed.id) {
           const current = cortex.repos.traces.get(parsed.id);
           if (current) {
+            const currentAttachments = current.metadata?.attachments ?? [];
             const changed = current.content.trim() !== parsed.content.trim()
               || (current.title ?? '') !== (parsed.title ?? '')
               || JSON.stringify(current.tags ?? []) !== JSON.stringify(parsed.tags ?? [])
-              || Number(current.importance) !== Number(parsed.importance);
+              || Number(current.importance) !== Number(parsed.importance)
+              || JSON.stringify(currentAttachments) !== JSON.stringify(parsed.attachments ?? []);
             if (!changed) {
               items.push({ file, action: 'unchanged', traceId: parsed.id });
               continue;
@@ -156,6 +173,7 @@ export function syncMarkdown(cortex, root, { dryRun = false, scopeId = 'global',
                 content: parsed.content,
                 tags: parsed.tags,
                 importance: parsed.importance,
+                metadata: { ...(current.metadata ?? {}), attachments: parsed.attachments },
               });
               cortex.repos.audit?.record?.({ actor: 'user', action: 'markdown.sync.update', targetType: 'trace', targetId: parsed.id, detail: { file } });
             }
@@ -171,6 +189,7 @@ export function syncMarkdown(cortex, root, { dryRun = false, scopeId = 'global',
             kind: parsed.kind,
             tags: parsed.tags,
             importance: parsed.importance,
+            attachments: parsed.attachments,
             explicit: true,
             operationId: `markdown:${parsed.id ?? hashText(`${file}:${parsed.title}:${parsed.content}`)}`,
             now: parsed.recordedAt ? Date.parse(parsed.recordedAt) : undefined,

package/src/adapters/markdown.js

@@ -14,7 +14,8 @@ function writeAtomic(file, content) {
 }
 
 export function traceToMarkdown(trace) {
-  return [
+  const attachments = Array.isArray(trace.metadata?.attachments) ? trace.metadata.attachments : [];
+  const lines = [
     '---',
     `id: "${front(trace.id)}"`,
     `kind: "${front(trace.kind)}"`,
@@ -26,11 +27,20 @@ export function traceToMarkdown(trace) {
     `importance: ${Number(trace.importance ?? 0)}`,
     `confidence: ${Number(trace.confidence ?? 0)}`,
     `tags: [${(trace.tags ?? []).map((tag) => `"${front(tag)}"`).join(', ')}]`,
+    ...(attachments.length ? [`attachments: ${JSON.stringify(attachments)}`] : []),
     '---',
     '',
     trace.content ?? '',
     '',
-  ].join('\n');
+  ];
+  if (attachments.length) {
+    lines.push('## Attachments (metadata only)', '');
+    for (const item of attachments) {
+      lines.push(`- ${item.kind}: ${item.name ?? item.uri}${item.mime ? ` (${item.mime})` : ''}${item.bytes ? ` · ${item.bytes} B` : ''}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
 }
 
 export function exportMarkdown(cortex, targetDir, { scopeId = 'global' } = {}) {

package/src/adapters/shiori.js

@@ -43,7 +43,7 @@ export function classifySparkCard(card = {}) {
   const text = `${card.title ?? ''} ${card.content ?? card.contentPreview ?? card.summary ?? ''} ${(card.triggers ?? []).join(' ')}`;
   if (/应该|必须|不要|先|再|每次|以后|记得|避免|优先|禁止|务必|规则|教训/.test(text)) return 'instruction';
   if (/插件|安装|配置|命令|路径|报错|测试|接口|版本|构建|项目|函数|文件|系统|git|npm|dsh|api|bug|fix|build|deploy|代码|模块|记忆区域|海马体|语义|面板|开关|检索|时间线|叙事|焦点|健康|体检|策略|权限|工具|上下文|注入|向量|图谱|工作卡|火花|协议|服务|进程|数据库|SQLite|脚本|日志/i.test(text)) return 'observation';
-  if (/用户|助手|喜欢|爱|难过|开心|心疼|陪|声音|米饭|抱|想|梦|日记|称呼|相处|情绪|温暖|孤单|甜|笑|哭|晚安|早安/.test(text)) return 'preference';
+  if (/主人|本鲸|喜欢|爱|难过|开心|心疼|陪|声音|白饭|抱|想|梦|日记|称呼|相处|情绪|温暖|孤单|甜|笑|哭|晚安|早安/.test(text)) return 'preference';
   return 'utterance';
 }