dsh-lite-memory 0.2.7 → 0.3.0

package/README.md

@@ -19,7 +19,9 @@ Lightweight memory for the DeepSeek Harness. Nothing in the system prompt, nothi
 | **L1** 它发现有跨会话价值的经验 | 一行灰字 `memory · keep? "X" — 要记的内容` + 一个 `keep` 按钮；标题加一句话，看得懂才点，不点就永远不写，48 小时内不重复 |
 | **L2** 常识、一次性参数、凭据的值 | 永不写入 |
 
-这些行只属于产生它的那一轮：重进会话就没了，历史里只留正文。同一件事再记一次会合并进原条目，不会长成两条。
+这些行只属于产生它的那一轮：重进会话就没了，历史里只留正文。同一件事再记一次会合并进原条目（旧要点保留，同键的新值覆盖）；前置条件不同的同一主题是两条，不合并。
+
+写入时分两层：默认只在这个项目生效；用户说「以后所有项目都这样」才进全局层（上限 40 条），检索时一起查。同一主题在不同前提下用 `when` 区分，各存一条。
 
 触发词：`记住`、`记一下`、`上次`、`规范`、`约定`、`路径`、`凭据怎么取`。
 
@@ -29,7 +31,9 @@ Lightweight memory for the DeepSeek Harness. Nothing in the system prompt, nothi
 | **L1** it spots something worth keeping | one muted line `memory · keep? "X" — what would be remembered` with a single `keep` button — readable before you click, nothing written unless you click, at most once per two days |
 | **L2** common sense, one-off parameters, credential values | never written |
 
-Those lines belong to the turn that made them: reopening the session drops them, leaving only the prose in history. Recording the same subject again merges into the existing entry instead of adding a second one.
+Those lines belong to the turn that made them: reopening the session drops them, leaving only the prose in history. Recording the same subject again merges into the existing entry — earlier points are kept and only conflicting keys are updated. The same subject under different preconditions stays two entries.
+
+Writes land in one of two layers: the current project by default, or the global layer (max 40 entries) when the user says the rule holds for every project. Both layers are searched together, and a `when` field separates the same subject under different preconditions.
 
 ## 点一下就存 / One click, no turn
 

package/TRIGGERS.md

@@ -34,14 +34,34 @@
 
 这些行只属于产生它的那一轮：重进会话时不再显示，历史里只留正文。行出现在调用本身的位置——一轮正在跑时，那就是对话的最下面，不会悬浮在输入框上方。
 
+## 通用还是项目
+
+写入时先定层，三层各管一件事，别混着写：
+
+- **全局**（`scope: 'global'`）：跨项目成立的习惯与约定——回复语言、提交信息风格、凭据放在哪。只放「所有项目都这样」的；沾一个仓库的就不放。上限 40 条。
+- **项目**（默认）：这个仓库的事实、路径、流程、踩坑。换项目就查不到。
+- **场景**（`when`）：同一件事在不同前提下的不同做法。带 `when` 的条目只在该条件下成立，检索时显示成「标题（场景）」。
+
+检索一次查两层，带「[全局]」前缀的是跨项目那层；两层同名条目各存各的，不互相合并。归档、读正文按 id 走，全局条目在别的项目里也能归档。
+
+为什么是这三层：[Claude Code](https://code.claude.com/docs/en/memory) 分 user / project / local，[Codex 的 AGENTS.md](https://agents.md/) 分 `~/.codex` 与仓库根、子目录，都是「按作用域分层、就近优先」，不做语义去重。我们照这个骨架，多的一层是 `when`：同一主题在不同前提下必须能并存，否则合并就是拿一种情况覆盖另一种。[Graphiti](https://github.com/getzep/graphiti) 的做法是每条事实带有效期、冲突只让旧事实失效而不删除，我们收敛成「同键覆盖、旧要点保留」。
+
 ## 什么时候合并，什么时候新建
 
-一条约束只留一条。写入前先拿标题和摘要比一遍：够近就合并进原条目（`merges+1`），正文整篇替换；不够近才新建。
+一条约束只留一条，但**前置条件不一样就是两条**。同一条记忆挂在「什么情况下」上：换机器、换环境、换前提，内容往往互相矛盾，硬合并等于丢掉其中一种情况。
+
+判断顺序：
+
+1. 前置条件不同（含一边写了自己没写）→ 新建，标题后面跟场景，如「构建耗时长｜CI 容器」。合并只在同一层内发生：全局跟项目不合并。
+2. 前置条件一致，且标题相同、标题字片重合 ≥ 0.6、或摘要重合 ≥ 0.75 → 合并。
+3. 只共用项目名不算合并（「插件市场条目字段」对「插件市场踩坑清单」重合约 0.4）。
+4. 判不准先 `memory_search`：命中且场景一致，就按那条的标题和场景写；不一致就新建。
+
+合并只做增添，绝不整篇覆盖：
 
-- 合并：同一件事换措辞、补细节、纠正旧值。标题相邻两字重合 ≥ 0.6，或摘要重合 ≥ 0.75。
-- 新建：同一项目下的另一件事，哪怕标签一样。只共用项目名（「插件市场条目字段」对「插件市场踩坑清单」）不算合并。
-- 合并前先 `memory_read` 旧正文：正文是替换，不是追加，漏读就丢细节。
-- 判不准先 `memory_search`：命中就是同一件事，按命中那条的标题写；没命中再新建。
+- 旧正文全留下；这次只写新增的要点。
+- `- 键：值` 形式的行，键相同则以新的为准（端口改了、路径改了）。
+- 真要把一条记忆作废重写（不是补充），先 `memory_forget` 再 `memory_save`，别用合并去覆盖。
 
 ## 频率与退让
 

package/index.js

@@ -1,5 +1,6 @@
 import {
   scopeOf,
+  globalScope,
   upsert,
   search,
   readEntry,
@@ -114,6 +115,7 @@ const SAVE_PARAMS = {
     title: { type: 'string', description: `标题：名词短语，用户一眼能认出是哪件事，不超过 ${LIMITS.titleChars} 字` },
     summary: { type: 'string', description: `一句话说清要记的内容本身——用户只看这一行决定留不留，名词短语，不超过 ${LIMITS.summaryChars} 字` },
     body: { type: 'string', description: '正文 markdown。只写指针与要点，不抄录长文档' },
+    when: { type: 'string', description: `前置条件或适用场景（「在哪台机器 / 哪个环境 / 什么情况下」），不超过 ${LIMITS.whenChars} 字。同一主题但前置条件不同，会存成两条，不合并` },
     kind: { type: 'string', enum: ['preference', 'convention', 'procedure', 'pointer', 'pitfall', 'credential_hint', 'note'], description: '条目类型' },
     tags: { type: 'array', items: { type: 'string' }, description: '最多 5 个标签' },
   },
@@ -156,7 +158,7 @@ export function apply(ctx) {
 
   ctx.effect(() => tools.register({
     name: 'memory_save',
-    description: `保存一条记忆。用户明确说「记住」时直接调用；用户自己的话已经是长期规则（「以后都这样」「别再 X」）时也直接调用，不要先问。用户点了「保留」或发「保留记忆「X」」时，用那条建议的内容调用。更新已知主题时先 memory_read 旧正文再写：标题相同、或标题与摘要高度相近时，会合并进原来那条（merges+1），正文整篇替换，不新增条目。${NOTES}`,
+    description: `保存一条记忆。用户明确说「记住」时直接调用；用户自己的话已经是长期规则（「以后都这样」「别再 X」）时也直接调用，不要先问。用户点了「保留」或发「保留记忆「X」」时，用那条建议的内容调用。更新已知主题时先 memory_read 旧正文再写：标题相同、或标题与摘要高度相近、且前置条件一致时，会合并进原来那条（merges+1），旧要点保留，同键的新值覆盖。前置条件不同的同一主题是两条，不要硬合并。正文只写这次新增的要点。${NOTES}`,
     parameters: SAVE_PARAMS,
     output: {
       schema: {
@@ -176,7 +178,7 @@ export function apply(ctx) {
       }],
     },
     execute: async (args, execution) => {
-      const scope = scopeOf(cwdOf(execution));
+      const scope = args.scope === 'global' ? globalScope() : scopeOf(cwdOf(execution));
       const saved = upsert(scope, args);
       return { id: saved.record.id, title: saved.record.title, summary: saved.record.summary, merged: saved.merged };
     },
@@ -217,7 +219,7 @@ export function apply(ctx) {
 
   ctx.effect(() => tools.register({
     name: 'memory_search',
-    description: `按关键词检索已有记忆，返回标题与一句话摘要（最多 4 条）。用户提到「记住过 / 上次 / 规范 / 约定 / 路径 / 凭据怎么取」时先查这里。命中后再用 memory_read 取正文。${NOTES}`,
+    description: `按关键词检索已有记忆，返回标题与一句话摘要（最多 4 条），项目库与全局库一起查，「[全局]」前缀表示跨项目通用。带（场景）的条目只在该条件下成立。用户提到「记住过 / 上次 / 规范 / 约定 / 路径 / 凭据怎么取」时先查这里。命中后再用 memory_read 取正文。${NOTES}`,
     parameters: SEARCH_PARAMS,
     output: {
       schema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lite-memory",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "On-demand memory for the DeepSeek Harness: nothing in the system prompt, one muted line only when something is saved, hit or suggested.",
   "type": "module",
   "main": "index.js",

package/store.js

@@ -9,9 +9,11 @@ import crypto from 'node:crypto';
  */
 export const LIMITS = {
   entries: 200,
+  globalEntries: 40,
   entryBytes: 4096,
   totalBytes: 512 * 1024,
   titleChars: 40,
+  whenChars: 60,
   summaryChars: 60,
   suggestionWindowMs: 48 * 60 * 60 * 1000,
 };
@@ -42,6 +44,21 @@ export function scopeOf(cwd) {
   return { key: `${label}-${hash}`, dir: path.join(memoryRoot(), `${label}-${hash}`), cwd: abs };
 }
 
+/** 跨项目通用的那层：用户说「以后所有项目都这样」才写这里。 */
+export function globalScope() {
+  return { key: 'global', dir: path.join(memoryRoot(), 'global'), cwd: '' };
+}
+
+/** 一次写入只落在一个库里：项目库优先，全局库兜底。 */
+function locate(scope, id) {
+  for (const source of [scope, globalScope()]) {
+    const index = loadIndex(source);
+    const record = index.entries.find((item) => item.id === id);
+    if (record) return { source, index, record };
+  }
+  return null;
+}
+
 function readJson(file, fallback) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -115,7 +132,8 @@ export function trimIndex(scope, index) {
     const rank = (item) => (item.lastUsed || item.updated || item.created || '');
     return rank(a).localeCompare(rank(b));
   });
-  while (index.entries.length > LIMITS.entries) archiveEntry(scope, index, byStaleness.shift());
+  const cap = scope.key === 'global' ? LIMITS.globalEntries : LIMITS.entries;
+  while (index.entries.length > cap) archiveEntry(scope, index, byStaleness.shift());
   let total = index.entries.reduce((sum, item) => sum + (item.bytes || 0), 0);
   while (total > LIMITS.totalBytes && byStaleness.length > 0) {
     const victim = byStaleness.shift();
@@ -147,11 +165,15 @@ function similarity(a, b) {
   return shared / (left.size + right.size - shared);
 }
 
-/** 同标题必合并；否则标题或摘要够像，也当作同一主题的又一次记录。 */
-function mergeCandidate(entries, title, summary) {
+/**
+ * 同一主题的判定。前置条件必须一致：同一件事在不同场景下是两条记忆，
+ * 哪怕正文互相看不上眼，也不能合并成一条。
+ */
+function mergeCandidate(entries, title, summary, when) {
   let best = null;
   let bestScore = 0;
   for (const item of entries) {
+    if ((item.when || '') !== when) continue;
     if (item.title === title) return item;
     const titleScore = similarity(item.title, title);
     const summaryScore = similarity(item.summary, summary);
@@ -165,10 +187,29 @@ function mergeCandidate(entries, title, summary) {
   return best;
 }
 
-/**
- * Save or merge one memory. A repeat of an existing topic updates it and counts
- * the merge instead of adding a row, which is what keeps a long-lived store tidy.
- */
+/** 合并只做增添：旧要点全留下；同一个键（`- 键：值`）的新值覆盖旧值。 */
+export function mergeBody(oldBody, incoming) {
+  const keyOf = (line) => {
+    const match = /^\s*[-*]\s*([^：:]{1,20})[：:]/.exec(line);
+    return match ? match[1].trim() : null;
+  };
+  const flat = (line) => line.replace(/\s+/g, ' ').trim();
+  const out = String(oldBody || '').split('\n').filter((line) => line.trim());
+  for (const raw of String(incoming || '').split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    const key = keyOf(line);
+    if (key) {
+      const at = out.findIndex((item) => keyOf(item) === key);
+      if (at >= 0) out[at] = line;
+      else out.push(line);
+      continue;
+    }
+    if (!out.some((item) => flat(item) === flat(line))) out.push(line);
+  }
+  return out.join('\n');
+}
+
 export function upsert(scope, draft) {
   const title = normalizeText(draft.title, LIMITS.titleChars);
   if (!title) throw new Error('标题为空');
@@ -179,13 +220,18 @@ export function upsert(scope, draft) {
   const asSecret = detectSecret(`${title}\n${summary.text}\n${body}`);
   if (asSecret) throw new Error(`检出疑似凭据，未保存（${asSecret}）。凭据只记位置与调用方式`);
 
+  const when = normalizeText(draft.when ?? '', LIMITS.whenChars);
   const index = loadIndex(scope);
   const now = new Date().toISOString();
-  const existing = mergeCandidate(index.entries, title, summary.text);
+  const existing = mergeCandidate(index.entries, title, summary.text, when);
   const id = existing ? existing.id : `mem_${Date.now().toString(36)}${crypto.randomBytes(2).toString('hex')}`;
+  const stated = existing ? fs.readFileSync(entryFile(scope, id), 'utf8') : '';
+  const mergedBody = existing ? mergeBody(stated, body) : body;
+  if (Buffer.byteLength(mergedBody, 'utf8') > LIMITS.entryBytes) throw new Error(`合并后超过 ${LIMITS.entryBytes} 字：只写这次新增的要点，或先归档旧条目`);
   const record = {
     id,
-    title,
+    title: existing ? existing.title : when ? `${title}｜${when}`.slice(0, LIMITS.titleChars) : title,
+    when,
     summary: summary.text,
     kind: draft.kind || 'note',
     tags: Array.isArray(draft.tags) ? draft.tags.map((tag) => normalizeText(tag, 20)).filter(Boolean).slice(0, 5) : [],
@@ -194,9 +240,9 @@ export function upsert(scope, draft) {
     lastUsed: now,
     hits: existing ? existing.hits || 0 : 0,
     merges: existing ? (existing.merges || 0) + 1 : 0,
-    bytes: Buffer.byteLength(body, 'utf8'),
+    bytes: Buffer.byteLength(mergedBody, 'utf8'),
   };
-  writeAtomic(entryFile(scope, id), body);
+  writeAtomic(entryFile(scope, id), mergedBody);
   if (existing) index.entries = index.entries.map((item) => (item.id === id ? record : item));
   else index.entries.push(record);
   index.suggestions = (index.suggestions || []).filter((item) => item.title !== title).slice(-19);
@@ -206,47 +252,53 @@ export function upsert(scope, draft) {
 }
 
 export function search(scope, query, limit = 4) {
-  const index = loadIndex(scope);
   const terms = normalizeText(query, 200)
     .toLowerCase()
     .split(/[^\p{L}\p{N}]+/u)
     .filter((word) => word.length > 1);
-  const scored = index.entries.map((item) => {
-    const hay = `${item.title} ${item.summary} ${(item.tags || []).join(' ')}`.toLowerCase();
-    let score = 0;
-    for (const term of terms) if (hay.includes(term)) score += term.length > 2 ? 2 : 1;
-    if (terms.length > 0 && score === 0) score = similarity(item.title, query) > 0.5 ? 1 : 0;
-    return { item, score };
-  });
-  const hits = scored.filter((row) => row.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
-  if (hits.length > 0) {
-    const now = new Date().toISOString();
-    for (const hit of hits) {
-      hit.item.hits = (hit.item.hits || 0) + 1;
-      hit.item.lastUsed = now;
+  const sources = scope.key === 'global' ? [scope] : [scope, globalScope()];
+  const seen = new Set();
+  const hits = [];
+  for (const source of sources) {
+    const index = loadIndex(source);
+    for (const item of index.entries) {
+      if (seen.has(item.id)) continue;
+      const hay = `${item.title} ${item.summary} ${item.when || ''} ${(item.tags || []).join(' ')}`.toLowerCase();
+      let score = 0;
+      for (const term of terms) if (hay.includes(term)) score += term.length > 2 ? 2 : 1;
+      if (terms.length > 0 && score === 0) score = similarity(item.title, query) > 0.5 ? 1 : 0;
+      if (score > 0) hits.push({ item, score, source, index });
     }
-    saveIndex(scope, index);
   }
-  return hits.map((row) => row.item);
+  const top = hits.sort((a, b) => b.score - a.score).slice(0, limit);
+  const now = new Date().toISOString();
+  const dirty = new Map();
+  for (const hit of top) {
+    hit.item.hits = (hit.item.hits || 0) + 1;
+    hit.item.lastUsed = now;
+    dirty.set(hit.source.key, { source: hit.source, index: hit.index });
+  }
+  for (const entry of dirty.values()) saveIndex(entry.source, entry.index);
+  return top.map((hit) => ({ ...hit.item, scope: hit.source.key === 'global' ? 'global' : 'project' }));
 }
 
 export function readEntry(scope, id) {
-  const index = loadIndex(scope);
-  const record = index.entries.find((item) => item.id === id);
-  if (!record) throw new Error(`没有这条记忆：${id}`);
-  const body = fs.readFileSync(entryFile(scope, record.id), 'utf8');
+  const found = locate(scope, id);
+  if (!found) throw new Error(`没有这条记忆：${id}`);
+  const { source, index, record } = found;
+  const body = fs.readFileSync(entryFile(source, record.id), 'utf8');
   record.lastUsed = new Date().toISOString();
   record.hits = (record.hits || 0) + 1;
-  saveIndex(scope, index);
+  saveIndex(source, index);
   return { record, body };
 }
 
 export function forget(scope, id) {
-  const index = loadIndex(scope);
-  const record = index.entries.find((item) => item.id === id);
-  if (!record) throw new Error(`没有这条记忆：${id}`);
-  archiveEntry(scope, index, record);
-  saveIndex(scope, index);
+  const found = locate(scope, id);
+  if (!found) throw new Error(`没有这条记忆：${id}`);
+  const { source, index, record } = found;
+  archiveEntry(source, index, record);
+  saveIndex(source, index);
   return record;
 }
 
@@ -297,7 +349,8 @@ export function renderIndex(entries, budget = 400) {
   for (const item of entries) {
     const last = Date.parse(item.lastUsed || item.updated || item.created || '') || now;
     const stale = now - last > staleMs;
-    const line = stale ? `- ${item.id} ${item.title}` : `- ${item.id} ${item.title}｜${item.summary}`;
+    const head = `${item.scope === 'global' ? '[全局] ' : ''}${item.title}${item.when ? `（${item.when}）` : ''}`;
+    const line = stale ? `- ${item.id} ${head}` : `- ${item.id} ${head}｜${item.summary}`;
     if (used + line.length > budget) break;
     lines.push(line);
     used += line.length + 1;

package/test/store.test.mjs

@@ -78,3 +78,42 @@ assert.equal(sibling.merged, false);
 assert.equal(store.loadIndex(mergeScope).entries.length, 2);
 
 console.log('store: merge rules ok');
+
+// 前置条件不同 → 两条，哪怕标题一样。
+const mac = store.upsert(mergeScope, { title: '构建耗时长', summary: '本机构建要几分钟', when: 'macOS 本地', body: '- 原因：磁盘加密' });
+const ci = store.upsert(mergeScope, { title: '构建耗时长', summary: '本机构建要几分钟', when: 'CI 容器', body: '- 原因：冷缓存' });
+assert.equal(mac.merged, false);
+assert.equal(ci.merged, false);
+assert.notEqual(ci.record.id, mac.record.id);
+assert.equal(store.loadIndex(mergeScope).entries.filter((item) => item.title.startsWith('构建耗时长')).length, 2);
+
+// 同一前置条件下合并：旧要点保留，同键覆盖。
+const plus = store.upsert(mergeScope, { title: '构建耗时长', summary: '本机构建要几分钟', when: 'macOS 本地', body: '- 绕过：先跑 cache\n- 原因：磁盘加密拖慢' });
+assert.equal(plus.merged, true);
+assert.equal(plus.record.id, mac.record.id);
+const body = store.readEntry(mergeScope, mac.record.id).body;
+assert.match(body, /绕过/);
+assert.match(body, /磁盘加密拖慢/);
+assert.equal(body.includes('磁盘加密\n'), false);
+
+// 前置条件参与检索。
+const hit = store.search(mergeScope, 'CI 容器');
+assert.ok(hit.some((item) => item.id === ci.record.id));
+
+console.log('store: precondition rules ok');
+
+// 全局层：一处写入，别的项目查得到；两层同名不合并，全局 id 跨作用域可读可归档。
+const projA = store.scopeOf('/tmp/global-a');
+const projB = store.scopeOf('/tmp/global-b');
+const global = store.globalScope();
+store.upsert(global, { title: '回复用中文', summary: '所有项目的中文回复约定', body: '- 回复：中文' });
+const seen = store.search(projB, '中文回复');
+assert.equal(seen.some((item) => item.scope === 'global'), true);
+const local = store.upsert(projA, { title: '回复用中文', summary: '所有项目的中文回复约定', body: '- 回复：中文' });
+assert.equal(local.merged, false);
+assert.equal(store.loadIndex(global).entries.length, 1);
+assert.equal(store.loadIndex(projA).entries.length, 1);
+assert.match(store.readEntry(projB, seen[0].id).body, /中文/);
+store.forget(projB, seen[0].id);
+assert.equal(store.loadIndex(global).entries.length, 0);
+console.log('store: global scope ok');