soulbridge 0.0.5 → 0.0.7

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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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,50 @@ async function main() {
             out({ ok: true, file: resolve(file), turns: turns.length, skipped, reflected, dryRun });
             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 +371,8 @@ async function main() {
                 '  import --in <file>              导入 JSONL',
                 '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
                 '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',
-                '  stats                           看状态',
+                '  status                          一眼看它是否在工作',
+                '  stats                           看原始状态（JSON）',
                 '  demo                            端到端演示（无需模型）',
                 '',
                 'env: SOULBRIDGE_DB, SOULBRIDGE_SOUL, SOULBRIDGE_USER, SOULBRIDGE_NAME,',

package/dist/packages/cli/src/llm-analyzer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Optional LLM-backed affect analyzer (ADR 0015).
+ *
+ * Deliberately lives in the CLI package, not in core: core must stay pure and
+ * offline. Opt-in only; every failure is thrown so the caller can degrade to
+ * the lexicon analyzer. The raw text never leaves the machine unless the user
+ * configured an endpoint.
+ */
+import type { AffectAnalyzer } from '../../core/src/index.ts';
+export interface LlmAnalyzerOptions {
+    /** Base URL, e.g. http://localhost:11434/v1 (Ollama) or any OpenAI-compatible endpoint. */
+    url: string;
+    model: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    /** Confidence is capped so a self-assured model cannot bypass the injection gate. */
+    maxConfidence?: number;
+}
+export declare function createLlmAnalyzer(options: LlmAnalyzerOptions): AffectAnalyzer;
+/** Build the analyzer from env vars, or null when not configured. */
+export declare function llmAnalyzerFromEnv(): AffectAnalyzer | null;

package/dist/packages/core/src/affect/analyze.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Rule-based affect analyzer (ADR 0016 budget: 8 rules, no narrow phrases).
+ *
+ * Rules implemented here:
+ *   R1 lexicon hit           R2 negation window (3 tokens)
+ *   R3 degree window (2)     R4 punctuation emphasis (!! ?? ……)
+ *   R5 repeated characters   R6 withdrawal phrases (abstain, never injected)
+ *   R7 code fences skipped   R8 very short input halves confidence
+ *
+ * Pure function: no I/O, no model, no globals besides a per-lexicon cache.
+ */
+import type { AffectSignal } from '../types.ts';
+import type { Lexicon } from './lexicon.ts';
+export declare const MAX_INPUT_CHARS = 32000;
+export declare const NEGATION_WINDOW = 3;
+export declare const DEGREE_WINDOW = 2;
+export declare class AffectBudgetError extends Error {
+    readonly code = "BUDGET_EXCEEDED";
+    constructor(length: number);
+}
+/** Full-width punctuation → ASCII, strip code fences and shell lines, drop emoji. */
+export declare function normalizeForAffect(text: string): string;
+/** Max forward match over the lexicon dictionary; punctuation and spaces are separators. */
+export declare function tokenizeForAffect(text: string, dict: Set<string>, maxLen: number): string[];
+export interface AnalyzeOptions {
+    lexicon?: Lexicon;
+}
+export declare function analyzeAffect(text: string, options?: AnalyzeOptions): AffectSignal;
+/** Lexicon analyzer as a port implementation (ADR 0015). */
+export declare const lexiconAnalyzer: {
+    id: string;
+    analyze(text: string): AffectSignal;
+};
+/** Empty signal helper so callers do not reach for the shared constant by accident. */
+export declare function emptyAffect(analyzer?: string): AffectSignal;

package/dist/packages/core/src/affect/directives.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Whitelisted style directives (ADR 0014).
+ *
+ * The prompt may only ever contain text from this catalog. There is no code
+ * path that turns free-form analysis into prose, because a wrong "you seem
+ * angry" is worse than saying nothing.
+ */
+import type { AffectSignal } from '../types.ts';
+export type DirectiveId = 'hedging' | 'fragmented' | 'negative_high' | 'positive_high' | 'vague_terms';
+export interface Directive {
+    id: DirectiveId;
+    text: string;
+}
+export declare const DIRECTIVE_CATALOG: readonly Directive[];
+/** Which catalog entries the signal justifies, in priority order, capped at `max`. */
+export declare function selectDirectives(signal: AffectSignal, max?: number): Directive[];

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

@@ -0,0 +1,8 @@
+export type { AffectAnalyzer } from './port.ts';
+export { analyzeAffect, lexiconAnalyzer, emptyAffect, AffectBudgetError, normalizeForAffect, tokenizeForAffect, MAX_INPUT_CHARS, } from './analyze.ts';
+export type { AnalyzeOptions } from './analyze.ts';
+export { SEED_LEXICON } from './seed-lexicon.ts';
+export { validateLexicon, DEGREE_DELTA, NEGATORS, ABSTAIN_TERMS } from './lexicon.ts';
+export type { Lexicon, LexiconEntry, DegreeWords } from './lexicon.ts';
+export { DIRECTIVE_CATALOG, selectDirectives } from './directives.ts';
+export type { Directive, DirectiveId } from './directives.ts';

package/dist/packages/core/src/affect/lexicon.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lexicon contract (ADR 0013).
+ *
+ * We adopt the *structure* of the DUTIR taxonomy (7 categories, intensity 1-9,
+ * polarity) because structures are not copyrightable. We do NOT ship any word
+ * list derived from an academic lexicon: the seed list in seed-lexicon.ts is
+ * written for this project. Users may import their own lexicon and carry the
+ * licensing consequences themselves.
+ */
+import type { AffectCategory, AffectPolarity } from '../types.ts';
+export interface LexiconEntry {
+    category: AffectCategory;
+    /** 1..9 */
+    intensity: number;
+    polarity: AffectPolarity;
+}
+export interface DegreeWords {
+    weak: string[];
+    medium: string[];
+    strong: string[];
+    extreme: string[];
+}
+export interface Lexicon {
+    version: string;
+    lang: string;
+    entries: Record<string, LexiconEntry>;
+    fillers: string[];
+    hedges: string[];
+    vague: Record<string, string[]>;
+    degree: DegreeWords;
+}
+/** Multiplicative-ish adjustment applied to a hit's intensity. */
+export declare const DEGREE_DELTA: Record<keyof DegreeWords, number>;
+/** Words that flip polarity when they precede an emotion word. */
+export declare const NEGATORS: string[];
+/** Withdrawal phrases: no explicit emotion word, but the affect is negative and weak. */
+export declare const ABSTAIN_TERMS: string[];
+/**
+ * Validate an externally supplied lexicon. Returns human-readable problems;
+ * an empty array means the lexicon is usable.
+ */
+export declare function validateLexicon(value: unknown): string[];

package/dist/packages/core/src/affect/port.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The analyzer port (ADR 0015).
+ *
+ * Rules are the default; a small model can be plugged in without touching
+ * core. Async analyzers MUST be cancellable by timeout at the call site and
+ * MUST be degradable to the lexicon analyzer.
+ */
+import type { AffectSignal } from '../types.ts';
+export interface AffectAnalyzer {
+    readonly id: string;
+    analyze(text: string): AffectSignal | Promise<AffectSignal>;
+}

package/dist/packages/core/src/affect/rules.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Rule registry (ADR 0016).
+ *
+ * The budget is part of the design: eight rules, no exceptions. New cases are
+ * not fixed by adding a ninth rule — that is the signal to move to the model
+ * adapter instead. Every rule listed here must have a test and an ablation
+ * number in spec/affect.v0.md.
+ */
+export interface RuleDescriptor {
+    readonly id: string;
+    readonly name: string;
+    readonly summary: string;
+}
+export declare const RULES: readonly RuleDescriptor[];
+export declare const RULE_BUDGET = 8;
+export declare const SEED_ENTRY_BUDGET = 120;

package/dist/packages/core/src/affect/seed-lexicon.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Seed lexicon, written for this project (MIT).
+ *
+ * Hard budget (ADR 0016): <= 120 emotion entries. Growing this list is not a
+ * fix for a missing case; if the budget is exhausted, the next step is the
+ * model adapter, not more words.
+ *
+ * Structure follows the DUTIR taxonomy (7 categories, intensity 1-9); no word
+ * list from that resource is copied here (ADR 0013).
+ */
+import type { Lexicon } from './lexicon.ts';
+export declare const SEED_LEXICON: Lexicon;

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

@@ -0,0 +1,19 @@
+/**
+ * Context assembly: turn structured state into the text a host agent injects.
+ *
+ * Three rules:
+ *  - never cut a sentence in half (drop whole memories instead)
+ *  - every injected memory id is reported in `used`, so injection is auditable
+ *  - the affect section is opt-in by confidence, capped in size, and only ever
+ *    contains whitelisted sentences (ADR 0014)
+ */
+import type { ContextRequest, ContextResult, Emotion } from './types.ts';
+import type { SoulStore } from './store.ts';
+export declare const DEFAULT_MAX_CHARS = 1200;
+/** Characters reserved for the affect section; if it does not fit, it is dropped whole. */
+export declare const AFFECT_BUDGET = 160;
+/** Only the most recent user turn counts; older samples are for evaluation, not injection. */
+export declare const AFFECT_WINDOW_MS: number;
+/** Emotion → concrete behavioural instruction. Values are -2..+2. */
+export declare function styleDirectives(emotion: Emotion): string[];
+export declare function buildContext(store: SoulStore, request: ContextRequest, now?: number): ContextResult;

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

@@ -0,0 +1,73 @@
+/**
+ * soulbridge core — the personality layer.
+ *
+ * Public surface is deliberately tiny: a facade (`Soul`) over four verbs.
+ * Anything a host needs beyond this belongs in an adapter.
+ */
+export * from './types.ts';
+export type { SoulStore } from './store.ts';
+export { openSqlite, SCHEMA_VERSION, AFFECT_RETENTION_MS, DbNewerThanBinaryError } from './sqlite.ts';
+export { buildContext, styleDirectives, DEFAULT_MAX_CHARS, AFFECT_BUDGET, AFFECT_WINDOW_MS, } from './context.ts';
+export { reflect, ruleExtract, nextEmotion } from './reflect.ts';
+export { rank, scoreMemory, tokenize, relevance } from './scoring.ts';
+export * from './affect/index.ts';
+export { measureStyle } from './style/measure.ts';
+export type { StyleMetrics } from './style/measure.ts';
+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 { SoulStore } from './store.ts';
+import type { AffectAnalyzer } from './affect/port.ts';
+export interface SoulOptions {
+    store: SoulStore;
+    soulId: string;
+    userId: string;
+    name?: string;
+    /** When the soul was born. Defaults to now; backdate it to demo long relationships. */
+    createdAt?: number;
+    /** Device identity for sync bookkeeping (ADR 0021). Optional in local use. */
+    deviceId?: string;
+    /** Defaults to the lexicon analyzer; pass an LLM-backed one to opt in (ADR 0015). */
+    analyzer?: AffectAnalyzer;
+}
+export declare class Soul {
+    readonly store: SoulStore;
+    readonly soulId: string;
+    readonly userId: string;
+    readonly name: string;
+    readonly deviceId: string;
+    readonly analyzer: AffectAnalyzer;
+    constructor(options: SoulOptions);
+    /** Verb 1: session start. */
+    context(request?: Partial<ContextRequest>): ContextResult;
+    /** Verb 3: on demand. */
+    recall(query: string, limit?: number): ScoredMemory[];
+    /** Pure analysis, no storage. Async because the analyzer may call a model. */
+    analyze(text: string): Promise<AffectSignal>;
+    /**
+     * Verb 2: after each turn.
+     *
+     * The analyzer may be async (a model); any failure degrades to the lexicon
+     * analyzer. Emotion is computed from the turn only — never from affect.
+     */
+    observe(turn: Turn): Promise<ObserveResult>;
+    /**
+     * Explicit form of `observe`: the host decided this is worth keeping.
+     * Same write path, no extraction heuristics.
+     */
+    remember(content: string, options?: {
+        type?: MemoryType;
+        importance?: number;
+        visibility?: Visibility;
+    }): string;
+    /** Verb 4: session end. */
+    reflect(turns: Turn[], llm?: LlmFn): Promise<ReflectResult>;
+    stats(): {
+        memories: number;
+        emotion: Emotion;
+        name: string;
+    };
+    private analyzeTurn;
+}

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

@@ -48,6 +48,10 @@ export class Soul {
             userId: this.userId,
             query: request.query,
             maxChars: request.maxChars,
+            track: request.track,
+            types: request.types,
+            minImportance: request.minImportance,
+            maxItems: request.maxItems,
         });
     }
     /** Verb 3: on demand. */

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

@@ -0,0 +1,29 @@
+import type { Emotion, LlmFn, MemoryType, ReflectResult, Turn } from './types.ts';
+import type { SoulStore } from './store.ts';
+interface Draft {
+    type: MemoryType;
+    content: string;
+    importance: number;
+}
+interface Rule {
+    /** Stable id for tests and diagnostics. */
+    id: string;
+    type: MemoryType;
+    importance: number;
+    match: (text: string) => boolean;
+}
+/** 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;
+export interface ReflectOptions {
+    soulId: string;
+    userId: string;
+    turns: Turn[];
+    now?: number;
+    /** Reserved for richer extraction; unused in v0. */
+    llm?: LlmFn;
+}
+export declare function reflect(store: SoulStore, options: ReflectOptions): Promise<ReflectResult>;
+export {};

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

@@ -7,12 +7,39 @@
  */
 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;
 /** 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),
+    },
+    {
+        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,7 +50,7 @@ export function ruleExtract(turns) {
         if (turn.role !== 'user')
             continue;
         for (const rule of RULES) {
-            if (rule.re.test(turn.content)) {
+            if (rule.match(turn.content)) {
                 drafts.push({ type: rule.type, content: turn.content.trim(), importance: rule.importance });
                 break;
             }

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

@@ -0,0 +1,30 @@
+/**
+ * Retrieval scoring. Pure functions, no I/O.
+ *
+ * score = 0.35*relevance + 0.25*importance + 0.20*recency + 0.15*vividness + 0.05*recall
+ *
+ * The weights are a claim, not a truth: changing them changes behaviour, so they
+ * live here (one place) and are covered by tests.
+ */
+import type { Memory } from './types.ts';
+/** A memory's relevance halves every 30 days without being recalled. */
+export declare const RECENCY_HALF_LIFE_DAYS = 30;
+export declare const WEIGHTS: {
+    readonly relevance: 0.35;
+    readonly importance: 0.25;
+    readonly recency: 0.2;
+    readonly vividness: 0.15;
+    readonly recall: 0.05;
+};
+/**
+ * CJK text has no spaces, so single characters are too coarse and the whole
+ * sentence is too fine: use character bigrams. Latin runs become words.
+ */
+export declare function tokenize(input: string): string[];
+export declare function relevance(queryTokens: string[], memory: Memory): number;
+export declare function recency(reference: number, now: number): number;
+export declare function scoreMemory(memory: Memory, queryTokens: string[], now: number): number;
+export declare function rank(memories: Memory[], query: string, now: number): Array<{
+    memory: Memory;
+    score: number;
+}>;

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

@@ -0,0 +1,9 @@
+import type { SoulStore } from './store.ts';
+export declare const SCHEMA_VERSION = 2;
+export declare const AFFECT_RETENTION_MS: number;
+export declare class DbNewerThanBinaryError extends Error {
+    readonly code = "DB_NEWER_THAN_BINARY";
+    readonly dbVersion: number;
+    constructor(dbVersion: number);
+}
+export declare function openSqlite(file: string): SoulStore;

package/dist/packages/core/src/storage/config.d.ts

@@ -0,0 +1,22 @@
+export interface SoulConfig {
+    soulId: string;
+    userId: string;
+    name: string;
+    deviceId: string;
+}
+export declare const DEFAULT_SOUL_ID = "xiaoling";
+export declare const DEFAULT_USER_ID = "local";
+export declare const DEFAULT_NAME = "\u5C0F\u7075";
+export declare function soulbridgeHome(): string;
+export declare function configPath(): string;
+export declare function defaultDbPath(): string;
+export declare function newDeviceId(): string;
+/** DB location: explicit flag > env > home. Never the cwd. */
+export declare function resolveDbPath(explicit?: string): string;
+export declare function loadConfig(): SoulConfig | null;
+export declare function saveConfig(config: SoulConfig): void;
+/**
+ * Read the config, creating or completing it when needed.
+ * Env overrides win, but are not persisted (an override is per-process).
+ */
+export declare function ensureConfig(overrides?: Partial<SoulConfig>): SoulConfig;

package/dist/packages/core/src/storage/merge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Merge semantics for cross-device sync (ADR 0021).
+ *
+ * Pure functions, no I/O: the transport (folder sync, git, manual export) is
+ * someone else's problem; this file only decides who wins.
+ *
+ * Rule: higher `updatedAt` wins; on a tie the lexicographically larger
+ * `device` wins, so merging is deterministic regardless of arrival order.
+ */
+export interface SyncRecord {
+    id: string;
+    device: string;
+    at: number;
+    updatedAt: number;
+    deleted?: boolean;
+}
+export declare function pickLatest<T extends SyncRecord>(a: T, b: T): T;
+/** Union by id, keeping tombstones (deletion must survive a merge). */
+export declare function mergeRecords<T extends SyncRecord>(records: Iterable<T>): T[];
+/** A record is visible only if the winning version is not a tombstone. */
+export declare function isVisible(record: SyncRecord): boolean;
+export declare function liveRecords<T extends SyncRecord>(records: Iterable<T>): T[];

package/dist/packages/core/src/storage/steering.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Steering-file import (ADR 0022).
+ *
+ * AGENTS.md / CLAUDE.md are good at *shared, reviewed* conventions. We do not
+ * replace them; we read them once and turn the stable statements into
+ * memories that can travel across tools.
+ *
+ * Parsing is deliberately conservative: bullets and short standalone lines
+ * only. Code fences, tables, badges and links are skipped — importing a
+ * hundred lines of YAML is worse than importing nothing.
+ */
+import type { MemoryType } from '../types.ts';
+export interface SteeringDraft {
+    text: string;
+    type: MemoryType;
+    importance: number;
+    line: number;
+}
+export declare const STEERING_MAX_DRAFTS = 200;
+/** Lowercase, strip punctuation and whitespace — for duplicate detection only. */
+export declare function normalizeForDedupe(text: string): string;
+/**
+ * Extract memory candidates from a steering file.
+ * Headings are dropped on purpose: they carry structure, not statements.
+ */
+export declare function parseSteering(text: string): SteeringDraft[];

package/dist/packages/core/src/storage/transcript.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Portable transcript ingestion (ADR 0023).
+ *
+ * Host session stores are private and change shape without notice (the DSH
+ * store is a multi-frame zstd container whose later frames are not decodable
+ * with a standard decompressor). Rather than reverse-engineering it, the
+ * adapter contract is a plain JSONL file that any host can export.
+ *
+ * Accepted line shapes (first match wins):
+ *   {"role":"user","content":"…"}
+ *   {"type":"user","text":"…"}
+ *   {"message":{"role":"user","content":"…"}}
+ *   {"role":"user","content":[{"type":"text","text":"…"}]}
+ *
+ * Everything else (headers, tool calls, tool results, reasoning) is skipped.
+ */
+import type { Turn } from '../types.ts';
+export interface TranscriptParseResult {
+    turns: Turn[];
+    skipped: number;
+}
+export declare function parseTranscriptJsonl(text: string): TranscriptParseResult;

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

@@ -0,0 +1,24 @@
+/**
+ * The only port. Every added method is a storage engine's opinion leaking into
+ * the domain, so the surface stays deliberately small.
+ */
+import type { AffectSignal, Emotion, Identity, Memory, QuerySpec } from './types.ts';
+export interface SoulStore {
+    ensureSoul(identity: Identity): void;
+    identity(soulId: string): Identity | null;
+    emotion(soulId: string, userId: string): Emotion;
+    saveEmotion(soulId: string, userId: string, emotion: Emotion, now?: number): void;
+    put(memory: Memory): void;
+    /** Active, non-deleted memories visible to `userId` (own private + shared). */
+    query(spec: QuerySpec): Memory[];
+    /** Recall bookkeeping: recallCount++, lastRecalledAt = now. */
+    touch(ids: string[], now?: number): void;
+    /** 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. */
+    recentAffect(soulId: string, userId: string, sinceMs: number): AffectSignal[];
+    /** Drop samples older than `beforeMs`; returns rows removed. */
+    purgeAffect(beforeMs: number): number;
+    count(soulId: string, userId: string): number;
+    close(): void;
+}

package/dist/packages/core/src/style/measure.d.ts

@@ -0,0 +1,12 @@
+import type { Lexicon } from '../affect/lexicon.ts';
+export interface StyleMetrics {
+    /** Characters in the raw reply. */
+    length: number;
+    /** Hedge words per 100 characters. */
+    hedgeRate: number;
+    /** Question marks (full-width normalised). */
+    questions: number;
+    /** Whether the reply opens by restating or confirming the request. */
+    confirmFirst: boolean;
+}
+export declare function measureStyle(text: string, lexicon?: Lexicon): StyleMetrics;

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

@@ -0,0 +1,148 @@
+/**
+ * Domain model. Pure types + constants, no logic, no dependencies.
+ *
+ * Rule: if a field only makes sense for one storage engine, it does not belong here.
+ * (No `vector`, no `embeddingId`, no `rowid`.)
+ */
+export type MemoryType = 'semantic' | 'episodic' | 'strategy' | 'cognition' | 'relationship' | 'trait' | 'fact';
+export type Visibility = 'private' | 'shared';
+export type MemoryStatus = 'active' | 'superseded' | 'archived';
+export interface Memory {
+    id: string;
+    soulId: string;
+    userId: string;
+    type: MemoryType;
+    content: string;
+    /** 1..10. How much this is worth remembering at all. */
+    importance: number;
+    /** 0..1. Decays over time; a vivid memory surfaces more easily. */
+    vividness: number;
+    recallCount: number;
+    status: MemoryStatus;
+    visibility: Visibility;
+    keywords: string[];
+    createdAt: number;
+    lastRecalledAt?: number;
+    validFrom?: number;
+    validUntil?: number;
+    supersededBy?: string;
+    /** Last-writer-wins clock for cross-device merge (ADR 0021). */
+    updatedAt?: number;
+    /** Tombstone; deletion is never physical on the first pass. */
+    deletedAt?: number;
+}
+export interface Identity {
+    soulId: string;
+    name: string;
+    creator?: string;
+    createdAt: number;
+}
+/** Six dimensions, each -2..+2. Baseline is slightly positive. */
+export interface Emotion {
+    passion: number;
+    bond: number;
+    tension: number;
+    selfRegard: number;
+    curiosity: number;
+    contentment: number;
+}
+export declare const DEFAULT_EMOTION: Emotion;
+export interface Turn {
+    role: 'user' | 'assistant';
+    content: string;
+    at?: number;
+}
+export interface ContextRequest {
+    soulId: string;
+    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;
+    used: string[];
+    dropped: number;
+    chars: number;
+    /** Present only when the affect section was actually injected. */
+    affect?: {
+        confidence: number;
+        directives: string[];
+    };
+}
+export interface RecallRequest {
+    soulId: string;
+    userId: string;
+    q: string;
+    limit?: number;
+}
+export interface ScoredMemory {
+    memory: Memory;
+    score: number;
+}
+export interface QuerySpec {
+    soulId: string;
+    userId: string;
+    status?: MemoryStatus[];
+    types?: MemoryType[];
+    limit?: number;
+}
+export interface ReflectResult {
+    memories: number;
+    superseded: number;
+    emotion: Emotion;
+}
+export interface ObserveResult {
+    written: number;
+    emotion: Emotion;
+    /** Analysis of the user turn. Empty signal for assistant turns or on failure. */
+    affect: AffectSignal;
+}
+/** Injected by the caller. `core` never imports a model SDK. */
+export type LlmFn = (prompt: string) => Promise<string> | string;
+export type AffectCategory = 'joy' | 'anger' | 'sadness' | 'fear' | 'disgust' | 'surprise';
+export type AffectPolarity = 'positive' | 'negative' | 'neutral';
+export interface AffectHit {
+    term: string;
+    category: AffectCategory;
+    /** 1..9, already adjusted by degree modifiers. */
+    intensity: number;
+    polarity: AffectPolarity;
+    negated: boolean;
+    position: number;
+}
+export interface AffectFeatures {
+    fillers: number;
+    hedges: number;
+    vague: number;
+    tokens: number;
+    /** meaningful tokens / all tokens, 0..1 */
+    density: number;
+}
+export interface AffectSignal {
+    /** Which analyzer produced this: 'lexicon' | 'llm' | 'none'. */
+    analyzer: string;
+    hits: AffectHit[];
+    dominant: AffectCategory | null;
+    intensity: number;
+    valence: number;
+    arousal: number;
+    features: AffectFeatures;
+    confidence: number;
+    /** True when the text looks like withdrawal ("行吧", "随便") but no explicit emotion word. */
+    abstain: boolean;
+}
+export declare const EMPTY_AFFECT: AffectSignal;
+/** Wire version of the four verbs. Additive changes bump MINOR (ADR 0005). */
+export declare const PROTOCOL_VERSION = "0.2";

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "soulbridge",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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"
   },