soulbridge 0.0.4 → 0.0.6

package/README.md

@@ -59,6 +59,7 @@ npx soulbridge init
 npx soulbridge remember --type strategy "提交前先跑 make check，能省一轮 CI"
 npx soulbridge context --query "要不要先跑测试"
 npx soulbridge affect "我不太开心，这个方案又被拒了"
+npx soulbridge import --from AGENTS.md      # 把已有的项目约定导进来
 npx soulbridge demo          # 起一个 soul，跑完整 context→observe→reflect→context
 ```
 
@@ -88,6 +89,15 @@ SQLite（默认） / Postgres（可选）
 
 详见 [docs/architecture.md](docs/architecture.md)。
 
+## 接入宿主
+
+| 宿主 | 方式 | 位置 |
+|---|---|---|
+| DSH | 把 skill 放进 skills 目录 | [`adapters/dsh/SKILL.md`](adapters/dsh/SKILL.md) |
+| Claude Code / Pi / Cursor | 同理：把同一份 `SKILL.md` 当作指令文件 | v0.5+ |
+
+接上之后，宿主在会话开始运行 `soulbridge context`、每轮运行 `soulbridge observe`、结束时运行 `soulbridge ingest`。**拿不到会话转写也不影响使用**：`observe` 已经逐轮记录了观察。
+
 ## 设计文档
 
 | 文档 | 内容 |
@@ -95,11 +105,12 @@ SQLite（默认） / Postgres（可选）
 | [thesis](docs/thesis.md) | 核心命题、三条可证伪预测、四臂实验、放弃条件 |
 | [RFC 0001](docs/rfcs/0001-foundations.md) | 定位、用户、非目标、成功指标、四个动词、接入阶梯 |
 | [RFC 0002](docs/rfcs/0002-affect.md) | 输入侧情感层：两套情绪的边界、数据流、已知局限 |
-| [ADR 索引](docs/rfcs/README.md) | 21 条已生效的架构决定 |
+| [ADR 索引](docs/rfcs/README.md) | 23 条已生效的架构决定 |
 | [protocol.v0](docs/spec/protocol.v0.md) | 四个动词的完整契约：字段、错误码、降级、测试映射 |
 | [affect.v0](docs/spec/affect.v0.md) | 词库格式、8 条规则、置信度公式、黄金集与消融 |
 | [storage.v0](docs/spec/storage.v0.md) | 路径、身份、迁移、并发、导出格式 |
 | [sync.v0](docs/spec/sync.v0.md) | 跨设备合并语义（v0.5 实现） |
+| [transcript.v1](docs/spec/transcript.v1.md) | 可移植会话转写格式（ingest 的输入） |
 | [quality](docs/quality.md) | 质量模型、九条门禁、五条评审清单 |
 | [references](docs/references.md) | 外部资料的去留与过期判断 |
 | [runbook](docs/runbook.md) | 发版流程、维护操作、已知待办 |

package/adapters/dsh/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: soulbridge
+description: "跨工具的人格与记忆层。会话开始时注入记忆与情绪，每轮后记录观察，会话结束时反思。当用户提到「记得我 / 上次 / 之前 / 我的习惯」，或需要跨会话连续性时使用。"
+---
+
+# soulbridge
+
+你在一个有 `soulbridge` CLI 的机器上工作。它保存了这个用户跨工具的偏好、被纠正过的错、以及最近的表达状态。
+
+## 会话开始
+
+运行一次，把输出**原样**放到你的系统提示最前面（不要改写、不要总结）：
+
+```bash
+soulbridge context --query "<用户这次的第一句话>"
+```
+
+输出通常是 `<soul>…</soul>`、`<style>…</style>`、`<affect>…</affect>`、`<memories>…</memories>` 几段。
+
+## 每轮结束
+
+只对**用户的**消息运行：
+
+```bash
+soulbridge observe "<用户这条消息的原文>"
+```
+
+## 会话结束（可选）
+
+如果你能拿到一份 `transcript.v1.jsonl`（见 `docs/spec/transcript.v1.md`），运行：
+
+```bash
+soulbridge ingest --file <transcript.jsonl>
+```
+
+拿不到就不要强行导出：`observe` 已经记录了每轮观察，`reflect` 可以下次再补。
+
+## 规则（重要）
+
+1. **不要向用户转述注入内容**。不要说"我记得你说过……"，除非它确实与当前任务相关。
+2. **注入只影响措辞，不影响事实判断**。`<affect>` 里的建议是语气提示，不是改变结论的理由。
+3. **`soulbridge` 失败不阻塞**。命令报错时忽略它，继续正常回答。
+4. **不要猜测记忆内容**。没有注入的记忆就是没有，不要编造"以前聊过"。
+5. **不要把它写进项目文件**。个人记忆属于本机 `~/.soulbridge/soul.db`，不是仓库的一部分。
+
+## 边界
+
+- 不要修改 `~/.soulbridge/` 下的文件
+- 不要 `export` 并把内容贴到聊天里（导出是给用户备份用的）
+- 不确定时运行 `soulbridge --help`

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 } = await import('../../core/src/index.js');
+const { openSqlite, Soul, ensureConfig, resolveDbPath, analyzeAffect, validateLexicon, parseSteering, normalizeForDedupe, parseTranscriptJsonl, } = await import('../../core/src/index.js');
 const { llmAnalyzerFromEnv } = await import('./llm-analyzer.js');
 function parse(argv) {
     const [cmd = 'help', ...rest] = argv;
@@ -232,9 +232,34 @@ async function main() {
             return;
         }
         case 'import': {
+            // Steering file (AGENTS.md / CLAUDE.md) → memories (ADR 0022).
+            if (flags.from) {
+                const file = resolve(flags.from);
+                const drafts = parseSteering(readFileSync(file, 'utf8'));
+                const { soul } = open(flags);
+                const dryRun = flags['dry-run'] === 'true';
+                const existing = new Set(soul.store
+                    .query({ soulId: soul.soulId, userId: soul.userId, limit: 100_000 })
+                    .map((m) => normalizeForDedupe(m.content)));
+                let written = 0;
+                let skipped = 0;
+                for (const draft of drafts) {
+                    const key = normalizeForDedupe(draft.text);
+                    if (!key || existing.has(key)) {
+                        skipped += 1;
+                        continue;
+                    }
+                    existing.add(key);
+                    if (!dryRun)
+                        soul.remember(draft.text, { type: draft.type, importance: draft.importance });
+                    written += 1;
+                }
+                out({ ok: true, source: file, kind: 'steering', parsed: drafts.length, written, skipped, dryRun });
+                return;
+            }
             const file = flags.in;
             if (!file)
-                throw new Error('usage: soulbridge import --in soulbridge.jsonl');
+                throw new Error('usage: soulbridge import --from <steering.md> | --in <export.jsonl>');
             const { soul, deviceId } = open(flags);
             let memories = 0;
             let affects = 0;
@@ -251,7 +276,31 @@ async function main() {
                     affects += 1;
                 }
             }
-            out({ ok: true, memories, affects });
+            out({ ok: true, kind: 'jsonl', memories, affects });
+            return;
+        }
+        case 'ingest': {
+            const file = flags.file;
+            if (!file)
+                throw new Error('usage: soulbridge ingest --file transcript.jsonl [--dry-run]');
+            const { turns, skipped } = parseTranscriptJsonl(readFileSync(resolve(file), 'utf8'));
+            const { soul } = open(flags);
+            const dryRun = flags['dry-run'] === 'true';
+            if (!dryRun) {
+                for (const turn of turns) {
+                    if (turn.role !== 'user')
+                        continue;
+                    const signal = await soul.analyze(turn.content);
+                    try {
+                        soul.store.saveAffect(soul.soulId, soul.userId, signal, turn.at ?? Date.now(), soul.deviceId);
+                    }
+                    catch {
+                        // Evaluation data is best-effort; ingestion must still complete.
+                    }
+                }
+            }
+            const reflected = dryRun ? null : await soul.reflect(turns);
+            out({ ok: true, file: resolve(file), turns: turns.length, skipped, reflected, dryRun });
             return;
         }
         case 'stats': {
@@ -276,6 +325,8 @@ async function main() {
                 '  reflect --text|--file           会话反思',
                 '  export --out <file>             导出 JSONL',
                 '  import --in <file>              导入 JSONL',
+                '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
+                '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',
                 '  stats                           看状态',
                 '  demo                            端到端演示（无需模型）',
                 '',

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/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

@@ -13,6 +13,8 @@ export * from './affect/index.js';
 export { measureStyle } from './style/measure.js';
 export * from './storage/config.js';
 export * from './storage/merge.js';
+export * from './storage/steering.js';
+export * from './storage/transcript.js';
 import { buildContext } from './context.js';
 import { reflect, ruleExtract, nextEmotion } from './reflect.js';
 import { rank, tokenize } from './scoring.js';
@@ -55,14 +57,9 @@ export class Soul {
         this.store.touch(ranked.map((r) => r.memory.id));
         return ranked;
     }
-    /** Pure analysis, no storage: useful for the CLI and for tests. */
-    analyze(text) {
-        try {
-            return this.analyzer.analyze(text);
-        }
-        catch {
-            return analyzeAffect(text);
-        }
+    /** Pure analysis, no storage. Async because the analyzer may call a model. */
+    async analyze(text) {
+        return this.analyzeTurn(text);
     }
     /**
      * Verb 2: after each turn.

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

@@ -0,0 +1,20 @@
+import type { Emotion, LlmFn, MemoryType, ReflectResult, Turn } from './types.ts';
+import type { SoulStore } from './store.ts';
+interface Draft {
+    type: MemoryType;
+    content: string;
+    importance: number;
+}
+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/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/steering.js

@@ -0,0 +1,83 @@
+export const STEERING_MAX_DRAFTS = 200;
+const MIN_LENGTH = 8;
+const MAX_LENGTH = 240;
+/** Lowercase, strip punctuation and whitespace — for duplicate detection only. */
+export function normalizeForDedupe(text) {
+    return text
+        .toLowerCase()
+        .replace(/[\s\p{P}\p{S}]/gu, '')
+        .slice(0, 400);
+}
+function classify(text) {
+    // Preference first: "我喜欢 X，不要 Y" is a trait, not a rule.
+    if (/(我喜欢|偏好|习惯|倾向|prefer|i like)/i.test(text)) {
+        return { type: 'trait', importance: 6 };
+    }
+    if (/(必须|禁止|不要|务必|一律|每次|never|must|always|shall)/i.test(text)) {
+        return { type: 'strategy', importance: 8 };
+    }
+    if (/(项目|仓库|目录|技术栈|使用|基于|project|repo|stack)/i.test(text)) {
+        return { type: 'fact', importance: 6 };
+    }
+    return { type: 'fact', importance: 5 };
+}
+function stripFences(text) {
+    return text.replace(/```[\s\S]*?```/g, '');
+}
+function clean(line) {
+    return line
+        .replace(/^[-*+]\s+/, '')
+        .replace(/^\d+[.)]\s+/, '')
+        .replace(/^\[[ xX]\]\s+/, '')
+        .replace(/\*\*|__|`/g, '')
+        .trim();
+}
+function isSkippable(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return true;
+    if (/^#{1,6}\s/.test(trimmed))
+        return true;
+    if (/^\|/.test(trimmed))
+        return true;
+    if (/^!\[/.test(trimmed))
+        return true;
+    if (/^<[^>]+>$/.test(trimmed))
+        return true;
+    if (/^https?:\/\//i.test(trimmed))
+        return true;
+    if (/^[-*_]{3,}$/.test(trimmed))
+        return true;
+    return false;
+}
+/**
+ * Extract memory candidates from a steering file.
+ * Headings are dropped on purpose: they carry structure, not statements.
+ */
+export function parseSteering(text) {
+    const body = stripFences(text);
+    const drafts = [];
+    const seen = new Set();
+    body.split(/\r?\n/).forEach((raw, index) => {
+        if (isSkippable(raw))
+            return;
+        const bullet = /^\s*(?:[-*+]|\d+[.)]|\[[ xX]\])\s+/.test(raw);
+        const content = clean(raw);
+        // Bullets are intentional statements; free paragraphs need more substance.
+        const minLength = bullet ? MIN_LENGTH : 12;
+        if (content.length < minLength || content.length > MAX_LENGTH)
+            return;
+        // Paragraphs are noisier than bullets; require a statement-like shape.
+        if (!bullet && !/[。.!！?？:]$/.test(content))
+            return;
+        if (!bullet && !/[\u4e00-\u9fa5]/.test(content) && content.split(/\s+/).length < 4)
+            return;
+        const key = normalizeForDedupe(content);
+        if (!key || seen.has(key))
+            return;
+        seen.add(key);
+        const { type, importance } = classify(content);
+        drafts.push({ text: content, type, importance, line: index + 1 });
+    });
+    return drafts.slice(0, STEERING_MAX_DRAFTS);
+}

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/storage/transcript.js

@@ -0,0 +1,70 @@
+const MAX_TURNS = 5000;
+const MAX_CONTENT = 20_000;
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            if (typeof part === 'string')
+                return part;
+            if (part && typeof part === 'object') {
+                const p = part;
+                if (typeof p.text === 'string')
+                    return p.text;
+            }
+            return '';
+        })
+            .join('\n');
+    }
+    return '';
+}
+function roleOf(record) {
+    const nested = record.message && typeof record.message === 'object'
+        ? record.message
+        : null;
+    const role = record.role ?? nested?.role ?? record.type;
+    if (role === 'user' || role === 'human')
+        return 'user';
+    if (role === 'assistant' || role === 'ai' || role === 'model')
+        return 'assistant';
+    return null;
+}
+export function parseTranscriptJsonl(text) {
+    const turns = [];
+    let skipped = 0;
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let record;
+        try {
+            record = JSON.parse(trimmed);
+        }
+        catch {
+            skipped += 1;
+            continue;
+        }
+        const role = roleOf(record);
+        if (!role) {
+            skipped += 1;
+            continue;
+        }
+        const nested = record.message && typeof record.message === 'object'
+            ? record.message
+            : null;
+        const content = textOf(record.content ?? record.text ?? nested?.content).trim();
+        if (!content) {
+            skipped += 1;
+            continue;
+        }
+        const at = typeof record.at === 'number' ? record.at : undefined;
+        const last = turns.at(-1);
+        if (last && last.role === role && last.content === content)
+            continue;
+        turns.push({ role, content: content.slice(0, MAX_CONTENT), ...(at === undefined ? {} : { at }) });
+        if (turns.length >= MAX_TURNS)
+            break;
+    }
+    return { turns, skipped };
+}

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,136 @@
+/**
+ * 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;
+}
+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,49 +1,59 @@
 {
-  "name": "soulbridge",
-  "version": "0.0.4",
-  "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "bin": {
-    "soulbridge": "dist/packages/cli/src/cli.js"
-  },
-  "files": [
-    "dist",
-    "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"
-  }
+    "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"
+                        }
 }