soulbridge 0.0.6 → 0.0.8

package/README.md

@@ -3,7 +3,7 @@
 > **给任何 agent 装上一个人格层。**
 > A personality layer for any agent — continuity, forgetting, and growth across tools.
 
-**状态：v0.0.4 · 已发布 npm · 接口仍在演进**
+**状态：v0.0.6 · 已发布 npm · 接口仍在演进**
 
 ---
 
@@ -111,6 +111,7 @@ SQLite（默认） / Postgres（可选）
 | [storage.v0](docs/spec/storage.v0.md) | 路径、身份、迁移、并发、导出格式 |
 | [sync.v0](docs/spec/sync.v0.md) | 跨设备合并语义（v0.5 实现） |
 | [transcript.v1](docs/spec/transcript.v1.md) | 可移植会话转写格式（ingest 的输入） |
+| [适配器索引](adapters/README.md) | 各宿主适配器与接入契约 |
 | [quality](docs/quality.md) | 质量模型、九条门禁、五条评审清单 |
 | [references](docs/references.md) | 外部资料的去留与过期判断 |
 | [runbook](docs/runbook.md) | 发版流程、维护操作、已知待办 |

package/adapters/README.md

@@ -0,0 +1,47 @@
+# 宿主适配器
+
+soulbridge 的核心不知道任何 agent 宿主的存在（[ADR 0024](../adr/0024-adapters.md)）。
+把四个动词接到具体宿主上的代码，都在这里列出的独立包里。
+
+## 现有适配器
+
+| 宿主 | 阶梯 | 形态 | 位置 |
+|---|---|---|---|
+| DSH | T0 | `SKILL.md`（模型自觉调用 CLI） | [dsh/SKILL.md](dsh/SKILL.md) |
+| DSH | T2 | cordis 插件（系统提示注入 + 事件观察） | [dsh-plugin-soulbridge](https://github.com/Jason0826/dsh-plugin-soulbridge) |
+
+> T1（会话转写摄取）与宿主无关：任何宿主导出 `transcript.v1.jsonl` 后，用
+> `soulbridge ingest --file` 即可，见 [spec/transcript.v1.md](../spec/transcript.v1.md)。
+
+## 适配器要做什么
+
+| 时机 | 调用 | 失败时 |
+|---|---|---|
+| 提示组装 | `context({ track: false })` | 不注入 |
+| 每条用户消息 | `observe(turn)` | 跳过 |
+| 会话结束 | `reflect(turns)` | 丢弃 |
+| 模型主动查询（可选） | `recall` / `remember` | 返回空 |
+
+## 三条禁止
+
+1. 不改变事实判断——affect 只影响措辞
+2. 不编造记忆——没注入的就是没有
+3. 不把个人记忆写进项目文件
+
+## 自己写一个适配器
+
+只需要 `soulbridge` 包暴露的：（TODO: 补 `soulbridge` 的 SDK 入口说明）
+
+```ts
+import { openSqlite, ensureConfig, resolveDbPath, Soul } from 'soulbridge';
+
+const config = ensureConfig();
+const soul = new Soul({
+  store: openSqlite(resolveDbPath()),
+  soulId: config.soulId,
+  userId: config.userId,
+  deviceId: config.deviceId,
+});
+```
+
+然后按上表在宿主的对应时机调用四个方法即可。

package/dist/packages/cli/src/cli.js

@@ -24,7 +24,7 @@ process.on('warning', (warning) => {
         return;
     process.stderr.write(`${warning.name}: ${warning.message}\n`);
 });
-const { openSqlite, Soul, ensureConfig, resolveDbPath, analyzeAffect, validateLexicon, parseSteering, normalizeForDedupe, parseTranscriptJsonl, } = await import('../../core/src/index.js');
+const { openSqlite, Soul, ensureConfig, resolveDbPath, analyzeAffect, validateLexicon, parseSteering, normalizeForDedupe, parseTranscriptJsonl, soulbridgeHome, } = await import('../../core/src/index.js');
 const { llmAnalyzerFromEnv } = await import('./llm-analyzer.js');
 function parse(argv) {
     const [cmd = 'help', ...rest] = argv;
@@ -303,6 +303,71 @@ async function main() {
             out({ ok: true, file: resolve(file), turns: turns.length, skipped, reflected, dryRun });
             return;
         }
+        case 'list': {
+            const { soul } = open(flags);
+            const memories = soul.list(flags.limit ? Number(flags.limit) : 20);
+            if (memories.length === 0) {
+                process.stdout.write('no memories yet\n');
+                return;
+            }
+            for (const memory of memories) {
+                const preview = memory.content.replace(/\s+/g, ' ').slice(0, 72);
+                process.stdout.write(`${memory.id}  ${memory.type.padEnd(9)} imp=${String(memory.importance).padEnd(2)} ${preview}\n`);
+            }
+            return;
+        }
+        case 'forget': {
+            const id = positional[0];
+            if (!id)
+                throw new Error('usage: soulbridge forget <memory-id>');
+            const { soul } = open(flags);
+            out({ ok: soul.forget(id), id });
+            return;
+        }
+        case 'status': {
+            const config = ensureConfig();
+            const dbPath = resolveDbPath(flags.db);
+            const store = openSqlite(dbPath);
+            const memories = store.query({ soulId: config.soulId, userId: config.userId, limit: 100_000 });
+            const samples = store.recentAffect(config.soulId, config.userId, 0);
+            store.close();
+            const byType = new Map();
+            for (const memory of memories)
+                byType.set(memory.type, (byType.get(memory.type) ?? 0) + 1);
+            const typeText = [...byType].sort((a, b) => b[1] - a[1]).map(([t, n]) => `${t} ${n}`).join(' · ') || '—';
+            let plugin = null;
+            try {
+                plugin = JSON.parse(readFileSync(resolve(soulbridgeHome(), 'plugin-state.json'), 'utf8'));
+            }
+            catch {
+                plugin = null;
+            }
+            const ago = (value) => {
+                if (typeof value !== 'number' || value <= 0)
+                    return '—';
+                const seconds = Math.max(0, Math.round((Date.now() - value) / 1000));
+                if (seconds < 60)
+                    return `${seconds}s ago`;
+                if (seconds < 3600)
+                    return `${Math.round(seconds / 60)}m ago`;
+                if (seconds < 86_400)
+                    return `${Math.round(seconds / 3600)}h ago`;
+                return `${Math.round(seconds / 86_400)}d ago`;
+            };
+            const lines = [
+                `soul       ${config.soulId} / ${config.userId}`,
+                `db         ${dbPath}`,
+                `memories   ${memories.length}  (${typeText})`,
+                `affect     ${samples.length} samples${samples.length > 0 ? ` · last ${ago(samples[0].at)}` : ''}`,
+                plugin
+                    ? `plugin     v${plugin.version ?? '?'} · applied ${ago(plugin.appliedAt)} · inject ${plugin.injects ?? 0} · observe ${plugin.observes ?? 0} · fail ${plugin.observeFails ?? 0}`
+                    : 'plugin     no heartbeat (plugin never loaded, or runs on another machine)',
+            ];
+            if (plugin?.lastError)
+                lines.push(`last error ${String(plugin.lastError)}`);
+            process.stdout.write(`${lines.join('\n')}\n`);
+            return;
+        }
         case 'stats': {
             const { soul, dbPath } = open(flags);
             out({ db: dbPath, ...soul.stats() });
@@ -327,7 +392,10 @@ async function main() {
                 '  import --in <file>              导入 JSONL',
                 '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
                 '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',
-                '  stats                           看状态',
+                '  list [--limit N]                看它记住了什么',
+                '  forget <id>                     忘掉一条记忆（墓碑）',
+                '  status                          一眼看它是否在工作',
+                '  stats                           看原始状态（JSON）',
                 '  demo                            端到端演示（无需模型）',
                 '',
                 'env: SOULBRIDGE_DB, SOULBRIDGE_SOUL, SOULBRIDGE_USER, SOULBRIDGE_NAME,',

package/dist/packages/core/src/context.js

@@ -53,13 +53,21 @@ export function buildContext(store, request, now = Date.now()) {
             }
         }
     }
-    const candidates = store.query({ soulId: request.soulId, userId: request.userId });
+    const candidates = store
+        .query({ soulId: request.soulId, userId: request.userId })
+        .filter((memory) => (request.types === undefined || request.types.includes(memory.type)) &&
+        (request.minImportance === undefined || memory.importance >= request.minImportance));
     const ranked = rank(candidates, request.query ?? '', now);
+    const maxItems = request.maxItems ?? Number.POSITIVE_INFINITY;
     let chars = sections.join('\n\n').length;
     let dropped = 0;
     const lines = [];
     const used = [];
     for (const { memory } of ranked) {
+        if (lines.length >= maxItems) {
+            dropped += 1;
+            continue;
+        }
         const line = `- [${memory.type}] ${memory.content}`;
         const cost = line.length + 1 + 10; // line + newline + section overhead share
         if (chars + cost > maxChars) {
@@ -73,7 +81,7 @@ export function buildContext(store, request, now = Date.now()) {
     if (lines.length > 0)
         sections.push(`<memories>\n${lines.join('\n')}\n</memories>`);
     const text = sections.join('\n\n');
-    if (used.length > 0)
+    if (request.track !== false && used.length > 0)
         store.touch(used, now);
     const result = { text, used, dropped, chars: text.length };
     if (affectMeta)

package/dist/packages/core/src/index.d.ts

@@ -17,7 +17,7 @@ export * from './storage/config.ts';
 export * from './storage/merge.ts';
 export * from './storage/steering.ts';
 export * from './storage/transcript.ts';
-import type { AffectSignal, ContextRequest, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, Visibility } from './types.ts';
+import type { AffectSignal, ContextRequest, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, Visibility } from './types.ts';
 import type { SoulStore } from './store.ts';
 import type { AffectAnalyzer } from './affect/port.ts';
 export interface SoulOptions {
@@ -42,6 +42,10 @@ export declare class Soul {
     constructor(options: SoulOptions);
     /** Verb 1: session start. */
     context(request?: Partial<ContextRequest>): ContextResult;
+    /** Every active memory, newest first. For `list` and for auditing injection. */
+    list(limit?: number): Memory[];
+    /** Tombstone one memory so it never reaches a prompt again. */
+    forget(id: string): boolean;
     /** Verb 3: on demand. */
     recall(query: string, limit?: number): ScoredMemory[];
     /** Pure analysis, no storage. Async because the analyzer may call a model. */

package/dist/packages/core/src/index.js

@@ -48,8 +48,20 @@ export class Soul {
             userId: this.userId,
             query: request.query,
             maxChars: request.maxChars,
+            track: request.track,
+            types: request.types,
+            minImportance: request.minImportance,
+            maxItems: request.maxItems,
         });
     }
+    /** Every active memory, newest first. For `list` and for auditing injection. */
+    list(limit = 50) {
+        return this.store.query({ soulId: this.soulId, userId: this.userId, limit });
+    }
+    /** Tombstone one memory so it never reaches a prompt again. */
+    forget(id) {
+        return this.store.forget(id);
+    }
     /** Verb 3: on demand. */
     recall(query, limit = 5) {
         const memories = this.store.query({ soulId: this.soulId, userId: this.userId });

package/dist/packages/core/src/reflect.d.ts

@@ -5,6 +5,27 @@ interface Draft {
     content: string;
     importance: number;
 }
+interface Rule {
+    /** Stable id for tests and diagnostics. */
+    id: string;
+    type: MemoryType;
+    importance: number;
+    match: (text: string) => boolean;
+    /** Optional rewrite: keep the instruction, drop the surrounding discussion. */
+    distill?: (text: string) => string | null;
+}
+/** Long strategies are noise in a prompt; keep the instruction, not the essay. */
+export declare const MAX_STRATEGY_CHARS = 80;
+/**
+ * Cut a standing instruction down to the clause that carries it.
+ *
+ * A user explains for two lines and states the rule once; storing the whole
+ * paragraph repeats the discussion into every future prompt. Find the trigger
+ * whose neighbourhood also carries a request, and keep from there.
+ */
+export declare function distillStrategy(text: string): string | null;
+/** Cheap, synchronous, no model. Deliberately conservative: false positives cost trust. */
+export declare const RULES: Rule[];
 export declare function ruleExtract(turns: Turn[]): Draft[];
 /** Corrections raise tension and lower passion; an ordinary session lets tension decay. */
 export declare function nextEmotion(current: Emotion, turns: Turn[]): Emotion;

package/dist/packages/core/src/reflect.js

@@ -7,12 +7,72 @@
  */
 import { randomUUID } from 'node:crypto';
 import { tokenize } from './scoring.js';
+/**
+ * A standing instruction needs both halves: when it applies, and what it asks
+ * for. A bare "每次" is usually a complaint ("每次都不能用"), so the trigger
+ * alone must not create a strategy.
+ */
+const TIME_TRIGGER = /(以后|下次|每次|从现在起|在.{0,12}之前|from now on|always)/i;
+const DIRECTIVE = /(先|需要|要|必须|应该|请|别|不要|务必|记得|need to|should|must|please)/i;
+/** Long strategies are noise in a prompt; keep the instruction, not the essay. */
+export const MAX_STRATEGY_CHARS = 80;
+/** How far after a trigger the request may sit and still belong to it. */
+const DIRECTIVE_WINDOW = 40;
+/**
+ * Cut a standing instruction down to the clause that carries it.
+ *
+ * A user explains for two lines and states the rule once; storing the whole
+ * paragraph repeats the discussion into every future prompt. Find the trigger
+ * whose neighbourhood also carries a request, and keep from there.
+ */
+export function distillStrategy(text) {
+    const trigger = new RegExp(TIME_TRIGGER.source, 'gi');
+    let match = trigger.exec(text);
+    let start = -1;
+    // The rule usually closes the paragraph ("...比如你每次…都需要…"), so the
+    // last qualifying trigger is the instruction, not the setup.
+    while (match !== null) {
+        const rest = text.slice(match.index);
+        if (DIRECTIVE.test(rest.slice(0, DIRECTIVE_WINDOW)))
+            start = match.index;
+        match = trigger.exec(text);
+    }
+    if (start < 0)
+        return null;
+    let clause = text.slice(start).replace(/^[\s，,、：:]+/, '');
+    clause = clause.replace(/^(比如|例如|就像|也就是说|你|我)\s*/g, '');
+    if (clause.length > MAX_STRATEGY_CHARS)
+        clause = clause.slice(0, MAX_STRATEGY_CHARS);
+    clause = clause.trim();
+    return clause.length > 0 ? clause : null;
+}
 /** Cheap, synchronous, no model. Deliberately conservative: false positives cost trust. */
-const RULES = [
-    { re: /(记住|别忘了|remember|don'?t forget)/i, type: 'fact', importance: 7 },
-    { re: /(我喜欢|我习惯|我偏好|我倾向|i prefer|i like)/i, type: 'trait', importance: 6 },
-    { re: /(以后|下次|每次|从现在起|from now on|always)/i, type: 'strategy', importance: 7 },
-    { re: /(我决定|就这么定|原则是|i decided|my rule)/i, type: 'cognition', importance: 7 },
+export const RULES = [
+    {
+        id: 'remember',
+        type: 'fact',
+        importance: 7,
+        match: (text) => /(记住|别忘了|remember|don'?t forget)/i.test(text),
+    },
+    {
+        id: 'preference',
+        type: 'trait',
+        importance: 6,
+        match: (text) => /(我喜欢|我习惯|我偏好|我倾向|i prefer|i like)/i.test(text),
+    },
+    {
+        id: 'standing-instruction',
+        type: 'strategy',
+        importance: 7,
+        match: (text) => TIME_TRIGGER.test(text) && DIRECTIVE.test(text),
+        distill: distillStrategy,
+    },
+    {
+        id: 'decision',
+        type: 'cognition',
+        importance: 7,
+        match: (text) => /(我决定|就这么定|原则是|i decided|my rule)/i.test(text),
+    },
 ];
 const CORRECTION = /(不对|不是这样|错了|你搞错|wrong|that'?s not right|incorrect)/i;
 const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
@@ -23,10 +83,13 @@ export function ruleExtract(turns) {
         if (turn.role !== 'user')
             continue;
         for (const rule of RULES) {
-            if (rule.re.test(turn.content)) {
-                drafts.push({ type: rule.type, content: turn.content.trim(), importance: rule.importance });
-                break;
-            }
+            if (!rule.match(turn.content))
+                continue;
+            // A rule may rewrite the turn; a strategy we cannot phrase is not stored.
+            const content = rule.distill ? rule.distill(turn.content) : turn.content.trim();
+            if (content)
+                drafts.push({ type: rule.type, content, importance: rule.importance });
+            break;
         }
     }
     return drafts;

package/dist/packages/core/src/sqlite.js

@@ -225,6 +225,12 @@ export function openSqlite(file) {
                     stmt.run(now, id);
             });
         },
+        forget(id, now = Date.now()) {
+            const result = withRetry(() => db
+                .prepare('UPDATE memories SET deleted_at = ?, updated_at = ? WHERE id = ? AND deleted_at IS NULL')
+                .run(now, now, id));
+            return Number(result.changes ?? 0) > 0;
+        },
         saveAffect(soulId, userId, signal, at, deviceId) {
             withRetry(() => {
                 db.prepare(`INSERT OR IGNORE INTO affect_samples

package/dist/packages/core/src/store.d.ts

@@ -13,6 +13,11 @@ export interface SoulStore {
     query(spec: QuerySpec): Memory[];
     /** Recall bookkeeping: recallCount++, lastRecalledAt = now. */
     touch(ids: string[], now?: number): void;
+    /**
+     * Tombstone a memory so it never surfaces again (sync-safe: the row stays for
+     * merge, the deletion wins by updatedAt). Returns false when no such active row.
+     */
+    forget(id: string, now?: number): boolean;
     /** Persist one affect sample (payload only; no raw text). */
     saveAffect(soulId: string, userId: string, signal: AffectSignal, at: number, deviceId?: string): void;
     /** Samples newer than `sinceMs`, newest first. */

package/dist/packages/core/src/types.d.ts

@@ -57,6 +57,18 @@ export interface ContextRequest {
     userId: string;
     query?: string;
     maxChars?: number;
+    /**
+     * Whether this call counts as a recall (increments recallCount / lastRecalledAt).
+     * Host adapters assemble prompts repeatedly per turn; pass false to preview
+     * context without inflating recall statistics. Defaults to true.
+     */
+    track?: boolean;
+    /** Only these memory types may be injected. Defaults to every type. */
+    types?: MemoryType[];
+    /** Skip memories below this importance (1..10). */
+    minImportance?: number;
+    /** Cap the number of injected memory lines. */
+    maxItems?: number;
 }
 export interface ContextResult {
     text: string;

package/package.json

@@ -1,59 +1,59 @@
 {
-    "name":  "soulbridge",
-    "version":  "0.0.6",
-    "description":  "A personality layer for any agent: continuity, forgetting, and growth across tools.",
-    "license":  "Apache-2.0",
-    "type":  "module",
-    "main":  "./dist/packages/core/src/index.js",
-    "types":  "./dist/packages/core/src/index.d.ts",
-    "exports":  {
-                    ".":  {
-                              "types":  "./dist/packages/core/src/index.d.ts",
-                              "import":  "./dist/packages/core/src/index.js"
-                          },
-                    "./package.json":  "./package.json"
-                },
-    "bin":  {
-                "soulbridge":  "dist/packages/cli/src/cli.js"
-            },
-    "files":  [
-                  "dist",
-                  "adapters",
-                  "README.md",
-                  "LICENSE",
-                  "NOTICE"
-              ],
-    "workspaces":  [
-                       "packages/*"
-                   ],
-    "engines":  {
-                    "node":  "\u003e=22.18"
-                },
-    "repository":  {
-                       "type":  "git",
-                       "url":  "git+https://github.com/Jason0826/soulbridge.git"
-                   },
-    "homepage":  "https://github.com/Jason0826/soulbridge#readme",
-    "bugs":  {
-                 "url":  "https://github.com/Jason0826/soulbridge/issues"
-             },
-    "keywords":  [
-                     "ai-agent",
-                     "memory",
-                     "personality",
-                     "continuity",
-                     "mcp",
-                     "claude-code"
-                 ],
-    "scripts":  {
-                    "build":  "tsc -p tsconfig.build.json",
-                    "test":  "node --test \"packages/core/test/*.test.ts\"",
-                    "demo":  "node packages/cli/src/cli.ts demo",
-                    "typecheck":  "tsc --noEmit",
-                    "prepublishOnly":  "npm run build \u0026\u0026 npm test"
-                },
-    "devDependencies":  {
-                            "@types/node":  "^26.6.5",
-                            "typescript":  "^7.0.2"
-                        }
+  "name": "soulbridge",
+  "version": "0.0.8",
+  "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/packages/core/src/index.js",
+  "types": "./dist/packages/core/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/packages/core/src/index.d.ts",
+      "import": "./dist/packages/core/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "soulbridge": "dist/packages/cli/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "adapters",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "workspaces": [
+    "packages/*"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jason0826/soulbridge.git"
+  },
+  "homepage": "https://github.com/Jason0826/soulbridge#readme",
+  "bugs": {
+    "url": "https://github.com/Jason0826/soulbridge/issues"
+  },
+  "keywords": [
+    "ai-agent",
+    "memory",
+    "personality",
+    "continuity",
+    "mcp",
+    "claude-code"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test \"packages/core/test/*.test.ts\"",
+    "demo": "node packages/cli/src/cli.ts demo",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
 }