soulbridge 0.0.103 → 0.0.105

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

@@ -14,7 +14,7 @@
  *   soulbridge demo
  */
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 // node:sqlite prints an ExperimentalWarning the moment it loads. Replace the default
 // printer with a filter: the CLI's own output stays clean, other warnings still show.
 // Must run before the dynamic import below, which is why that import is dynamic.
@@ -221,9 +221,27 @@ async function main() {
             return;
         }
         case 'export': {
+            // Two shapes: a legacy JSONL of memories (--out), and the portable bundle (--dir)
+            // that carries the whole record, a readable summary and the current injection.
+            if (flags.dir) {
+                const { soul } = open(flags);
+                const dir = resolve(String(flags.dir));
+                mkdirSync(dir, { recursive: true });
+                const bundle = soul.portableBundle();
+                writeFileSync(join(dir, 'archive.jsonl'), `${bundle.archive.join('\n')}\n`, 'utf8');
+                writeFileSync(join(dir, 'summary.md'), bundle.summary, 'utf8');
+                writeFileSync(join(dir, 'injection.txt'), bundle.injection, 'utf8');
+                out({
+                    ok: true,
+                    dir,
+                    records: bundle.archive.length,
+                    files: ['archive.jsonl', 'summary.md', 'injection.txt'],
+                });
+                return;
+            }
             const file = flags.out;
             if (!file)
-                throw new Error('usage: soulbridge export --out soulbridge.jsonl');
+                throw new Error('usage: soulbridge export --out <file> | --dir <directory>');
             const { soul, deviceId } = open(flags);
             const body = exportJsonl(soul, deviceId);
             const target = resolve(file);
@@ -409,6 +427,41 @@ async function main() {
             out({ db: dbPath, ...soul.stats() });
             return;
         }
+        case 'why': {
+            // The reader for the 依据 slot: a fact I said must be traceable to the turn I said it
+            // in, and a conclusion must be traceable to the facts that support it.
+            const factId = positional[0];
+            if (!factId)
+                throw new Error('usage: soulbridge why <factId>');
+            const { soul } = open(flags);
+            const fact = soul.store.fact(factId);
+            if (!fact) {
+                out({ ok: false, error: `no fact ${factId}` });
+                return;
+            }
+            const basisSlot = fact.slots.find((slot) => slot.slot === '依据' && slot.value.kind === 'text');
+            const turn = basisSlot?.value.kind === 'text' ? soul.store.turn(basisSlot.value.value) : null;
+            out({
+                id: fact.id,
+                statement: fact.statement,
+                role: fact.role,
+                status: fact.status,
+                source: fact.source,
+                basis: turn
+                    ? {
+                        turnId: turn.id,
+                        at: new Date(turn.at).toISOString(),
+                        userText: turn.userText,
+                        assistantText: turn.assistantText.slice(0, 200),
+                    }
+                    : null,
+                evidence: fact.slots
+                    .filter((slot) => slot.slot === '证据' && slot.value.kind === 'fact')
+                    .map((slot) => (slot.value.kind === 'fact' ? slot.value.factId : undefined))
+                    .filter(Boolean),
+            });
+            return;
+        }
         case 'demo':
             await demo();
             return;
@@ -425,6 +478,8 @@ async function main() {
                 '  recall <q> [--limit N]          召回',
                 '  reflect --text|--file           会话反思',
                 '  export --out <file>             导出 JSONL',
+                '  export --dir <directory>        导出可携带档案（archive/summary/injection）',
+                '  why <factId>                    这条事实的依据：来源轮次 / 证据',
                 '  import --in <file>              导入 JSONL',
                 '  import --from <steering.md>     导入 AGENTS.md / CLAUDE.md',
                 '  ingest --file <transcript.jsonl> 会话转写 → 记忆与情绪采样',

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

@@ -78,13 +78,22 @@ export function buildContext(store, request, now = Date.now()) {
         .facts({ soulId: request.soulId, userId: request.userId, limit: 300 })
         .filter((fact) => isActive(fact) &&
         (ANCHOR_ROLES.has(roleOf(fact)) || anchorTypes.has(fact.typeName ?? '') || explicitAnchor(fact)))
-        .map((fact) => ({ id: fact.id, label: fact.typeName ?? '事实', text: fact.statement, score: fact.confidence }));
+        .map((fact) => ({
+        id: fact.id,
+        label: fact.typeName ?? '事实',
+        text: fact.statement,
+        score: fact.confidence,
+        // ADR 0035: my own side of the exchange is inferred and must not read like something
+        // the user said. The marker is two characters; a per-line sentence would double the
+        // injection, so the explanation is written once below the block.
+        inferred: fact.source === 'inferred',
+    }));
     for (const memory of store.query({ soulId: request.soulId, userId: request.userId })) {
         if (request.types !== undefined && !request.types.includes(memory.type))
             continue;
         if (request.minImportance !== undefined && memory.importance < request.minImportance)
             continue;
-        anchors.push({ id: memory.id, label: memory.type, text: memory.content, score: memory.importance / 10 });
+        anchors.push({ id: memory.id, label: memory.type, text: memory.content, score: memory.importance / 10, inferred: false });
     }
     anchors.sort((a, b) => b.score - a.score);
     const maxItems = request.maxItems ?? Number.POSITIVE_INFINITY;
@@ -92,6 +101,7 @@ export function buildContext(store, request, now = Date.now()) {
     let dropped = 0;
     const lines = [];
     const used = [];
+    let sawInferred = false;
     for (const anchor of anchors) {
         if (lines.length >= maxItems) {
             dropped += 1;
@@ -99,7 +109,10 @@ export function buildContext(store, request, now = Date.now()) {
         }
         // Escaping can lengthen a line (one `&lt;` is four characters), so cost is charged
         // on the escaped text — the budget has to measure what actually gets injected.
-        const line = `- [${escapeBlockText(anchor.label)}] ${escapeBlockText(anchor.text)}`;
+        const marker = anchor.inferred ? '我: ' : '';
+        const line = `- ${marker}[${escapeBlockText(anchor.label)}] ${escapeBlockText(anchor.text)}`;
+        if (anchor.inferred)
+            sawInferred = true;
         const cost = line.length + 1 + 10; // line + newline + section overhead share
         if (chars + cost > maxChars) {
             dropped += 1;
@@ -111,6 +124,9 @@ export function buildContext(store, request, now = Date.now()) {
     }
     if (request.includeAnchors !== false && lines.length > 0)
         sections.push(`<memories>\n${lines.join('\n')}\n</memories>`);
+    if (sawInferred) {
+        sections.push('<source-notes>以「我:」开头的是我上一轮说的话，未经用户确认；没标的都是用户说的。</source-notes>');
+    }
     const text = sections.join('\n\n');
     if (request.track !== false && used.length > 0)
         store.touch(used, now);

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

@@ -30,7 +30,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, Correction, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, CommitResult, Entity, ExtractDraft, ConclusionDraft, Fact, ThreadAttribution, TurnThread, FactDetail, FactSpec, Gap, GapSpec, SessionHandoff, TurnFindResult, SessionSummary, TurnPair, TurnStep, Visibility } from './types.ts';
+import type { AffectSignal, ContextRequest, Correction, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, CommitResult, Entity, ExtractDraft, ConclusionDraft, Fact, ThreadAttribution, TurnThread, FactDetail, FactSpec, Gap, GapSpec, SessionHandoff, TurnFindResult, SessionSummary, TurnPair, TurnStep, PortableBundle, Visibility } from './types.ts';
 import type { SoulStore } from './store.ts';
 import type { AffectAnalyzer } from './affect/port.ts';
 import type { Rule } from './rules.ts';
@@ -80,6 +80,11 @@ export declare class Soul {
     readonly dedupeWindowMs: number;
     readonly onLlmRaw?: (raw: string) => void;
     constructor(options: SoulOptions);
+    /**
+     * Everything a host needs to carry this soul to another machine or tool:
+     * the full archive, a readable summary, and the injection the model would see.
+     */
+    portableBundle(now?: number): PortableBundle;
     /** Verb 1: session start. */
     context(request?: Partial<ContextRequest>): ContextResult;
     /**

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

@@ -21,6 +21,7 @@ export * from './storage/config.js';
 export * from './storage/merge.js';
 export * from './storage/steering.js';
 export * from './storage/transcript.js';
+import { buildPortableBundle } from './portable.js';
 import { FACT_STATUS, MEMORY_STATUS } from './config/status.js';
 import { HOLDER_WORDS } from './config/domains.js';
 import { isActive, isRetracted, roleOf } from './roles.js';
@@ -100,6 +101,15 @@ export class Soul {
             });
         }
     }
+    /**
+     * Everything a host needs to carry this soul to another machine or tool:
+     * the full archive, a readable summary, and the injection the model would see.
+     */
+    portableBundle(now = Date.now()) {
+        const dump = this.store.dump(this.soulId, this.userId);
+        const injection = this.context({}).text;
+        return buildPortableBundle(dump, this.soulId, this.userId, injection, now);
+    }
     /** Verb 1: session start. */
     context(request = {}) {
         // Spread, not a field list: an explicit list silently dropped every option

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

@@ -0,0 +1,17 @@
+/**
+ * Portable bundle: the whole record, a human-readable summary, and the injection text.
+ *
+ * Three layers, because they answer different questions (spec/vocabulary.v1 §7):
+ *   archive   — everything, including raw exchanges; the recipient can rebuild the store.
+ *   summary   — what a person can read in a minute: rules, profile, conclusions, promises,
+ *               entities, open gaps. No ids unless they help.
+ *   injection — what the model would see right now; the smallest useful transfer.
+ *
+ * Nothing here filters by importance. An export that silently drops "unimportant" rows
+ * cannot be the source of truth, and importance is a semantic judgement we do not store.
+ */
+import type { PortableDump, PortableBundle } from './types.ts';
+export declare function buildPortableSummary(dump: PortableDump, soulId: string, userId: string, now: number): string;
+/** One JSON object per line, tagged so a reader can stream it without a schema. */
+export declare function buildArchiveLines(dump: PortableDump): string[];
+export declare function buildPortableBundle(dump: PortableDump, soulId: string, userId: string, injection: string, now: number): PortableBundle;

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

@@ -0,0 +1,93 @@
+export function buildPortableSummary(dump, soulId, userId, now) {
+    const lines = [];
+    lines.push(`# soulbridge 档案 · ${userId}`);
+    lines.push('');
+    lines.push(`- soul: ${soulId}`);
+    lines.push(`- 导出时间: ${new Date(now).toISOString()}`);
+    lines.push(`- 规模: 事实 ${dump.facts.length} · 实体 ${dump.entities.length} · 线索 ${dump.threads.length} · 轮次 ${dump.turns.length} · 缺口 ${dump.gaps.length}`);
+    lines.push('');
+    const byRole = (role) => dump.facts.filter((fact) => fact.role === role && fact.status === 'active');
+    const slotText = (fact, name) => {
+        const slot = fact.slots.find((item) => item.slot === name);
+        return slot?.value.kind === 'text' ? slot.value.value : undefined;
+    };
+    const rules = byRole('rule');
+    if (rules.length > 0) {
+        lines.push(`## 规则（${rules.length}）`);
+        for (const rule of rules) {
+            const trigger = slotText(rule, '触发');
+            const action = slotText(rule, '动作') ?? rule.statement;
+            lines.push(trigger ? `- 当 ${trigger}：${action}` : `- ${action}`);
+        }
+        lines.push('');
+    }
+    const profile = byRole('profile');
+    if (profile.length > 0) {
+        lines.push(`## 画像（${profile.length}）`);
+        for (const line of profile)
+            lines.push(`- ${line.statement}`);
+        lines.push('');
+    }
+    const judgments = byRole('judgment');
+    if (judgments.length > 0) {
+        lines.push(`## 结论（${judgments.length}）`);
+        for (const line of judgments.slice(0, 30))
+            lines.push(`- ${line.statement}`);
+        lines.push('');
+    }
+    const promises = byRole('promise');
+    if (promises.length > 0) {
+        lines.push(`## 承诺（${promises.length}）`);
+        for (const line of promises)
+            lines.push(`- ${line.statement}`);
+        lines.push('');
+    }
+    if (dump.entities.length > 0) {
+        lines.push(`## 实体（${dump.entities.length}）`);
+        for (const entity of dump.entities.slice(0, 50)) {
+            const aliases = entity.aliases.length > 0 ? `（别名：${entity.aliases.join('、')}）` : '';
+            lines.push(`- ${entity.name} · ${entity.type}${aliases}`);
+        }
+        lines.push('');
+    }
+    const openGaps = dump.gaps.filter((gap) => gap.status === 'open');
+    if (openGaps.length > 0) {
+        lines.push(`## 未闭合的缺口（${openGaps.length}）`);
+        for (const gap of openGaps.slice(0, 20))
+            lines.push(`- ${gap.topic}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** One JSON object per line, tagged so a reader can stream it without a schema. */
+export function buildArchiveLines(dump) {
+    const lines = [];
+    // `record` is the discriminator, not `type`: Entity has its own `type` field, and a
+    // spread after the tag would silently overwrite it.
+    for (const entity of dump.entities)
+        lines.push(JSON.stringify({ record: 'entity', ...entity }));
+    for (const fact of dump.facts)
+        lines.push(JSON.stringify({ record: 'fact', ...fact }));
+    for (const thread of dump.threads)
+        lines.push(JSON.stringify({ record: 'thread', ...thread }));
+    for (const gap of dump.gaps)
+        lines.push(JSON.stringify({ record: 'gap', ...gap }));
+    for (const turn of dump.turns)
+        lines.push(JSON.stringify({ record: 'turn', ...turn }));
+    for (const step of dump.steps)
+        lines.push(JSON.stringify({ record: 'step', ...step }));
+    for (const correction of dump.corrections)
+        lines.push(JSON.stringify({ record: 'correction', ...correction }));
+    return lines;
+}
+export function buildPortableBundle(dump, soulId, userId, injection, now) {
+    return {
+        schemaVersion: 1,
+        exportedAt: now,
+        soulId,
+        userId,
+        summary: buildPortableSummary(dump, soulId, userId, now),
+        injection,
+        archive: buildArchiveLines(dump),
+    };
+}

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

@@ -646,6 +646,45 @@ export function openSqlite(file) {
                 deviceId: row.device_id == null ? undefined : String(row.device_id),
             }));
         },
+        corrections(soulId, userId, limit = 100_000) {
+            return this.recentCorrections(soulId, userId, limit);
+        },
+        dump(soulId, userId) {
+            const facts = this.facts({ soulId, userId, limit: 100_000 });
+            const entities = this.findEntities({ soulId, userId, limit: 100_000 });
+            const threads = db
+                .prepare('SELECT * FROM threads WHERE soul_id = ? AND user_id = ? ORDER BY opened_at ASC')
+                .all(soulId, userId).map(rowToThread);
+            const gaps = db
+                .prepare('SELECT * FROM gaps WHERE soul_id = ? AND user_id = ? ORDER BY opened_at ASC')
+                .all(soulId, userId).map(rowToGap);
+            const turns = db
+                .prepare('SELECT * FROM turns WHERE soul_id = ? AND user_id = ? ORDER BY created_at ASC')
+                .all(soulId, userId).map(rowToTurnPair);
+            const steps = db
+                .prepare(`SELECT s.* FROM steps s JOIN turns t ON t.id = s.turn_id
+            WHERE t.soul_id = ? AND t.user_id = ? ORDER BY s.turn_id, s.idx`)
+                .all(soulId, userId);
+            return {
+                entities,
+                facts,
+                threads,
+                gaps,
+                turns,
+                steps: steps.map((row) => ({
+                    turnId: String(row.turn_id),
+                    idx: Number(row.idx),
+                    kind: row.kind,
+                    text: row.text == null ? undefined : String(row.text),
+                    toolName: row.tool_name == null ? undefined : String(row.tool_name),
+                    toolArgsChars: row.tool_args_chars == null ? undefined : Number(row.tool_args_chars),
+                    toolResultChars: row.tool_result_chars == null ? undefined : Number(row.tool_result_chars),
+                    ok: row.ok == null ? undefined : Boolean(row.ok),
+                    at: Number(row.at),
+                })),
+                corrections: this.recentCorrections(soulId, userId, 100_000),
+            };
+        },
         countCorrections(soulId, userId) {
             const row = db
                 .prepare('SELECT COUNT(*) AS n FROM corrections WHERE soul_id = ? AND user_id = ?')

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

@@ -2,7 +2,7 @@
  * 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, Correction, Emotion, Entity, EntityQuery, EntitySpec, Fact, FactQuery, FactRole, FactSpec, FactStatus, Gap, GapSpec, Identity, Memory, QuerySpec, SessionSummary, SlotValue, TurnPair, TurnPairSpec, TurnFindResult, TurnFindSpec, TurnSpec, TurnStep, TurnThread, ThreadSpec } from './types.ts';
+import type { AffectSignal, Correction, Emotion, Entity, EntityQuery, EntitySpec, Fact, FactQuery, FactRole, FactSpec, FactStatus, Gap, GapSpec, Identity, Memory, PortableDump, QuerySpec, SessionSummary, SlotValue, TurnPair, TurnPairSpec, TurnFindResult, TurnFindSpec, TurnSpec, TurnStep, TurnThread, ThreadSpec } from './types.ts';
 export interface SoulStore {
     ensureSoul(identity: Identity): void;
     identity(soulId: string): Identity | null;
@@ -103,6 +103,10 @@ export interface SoulStore {
     putGap(spec: GapSpec): Gap;
     openGaps(soulId: string, userId: string, limit?: number): Gap[];
     closeGap(id: string, closedByFactId?: string, at?: number): void;
+    /** Corrections the user made, newest first — the objective signal for behaviour changes. */
+    corrections(soulId: string, userId: string, limit?: number): Correction[];
+    /** Everything a portable bundle needs, scoped to one soul/user. */
+    dump(soulId: string, userId: string): PortableDump;
     /** Exchanges visible to `userId`; scored against `spec.query` when given. */
     recallTurnPairs(spec: TurnPairSpec): TurnPair[];
     countTurnPairs(soulId: string, userId: string, sessionId?: string): number;

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

@@ -61,6 +61,33 @@ export interface TurnPair {
     metadata: Record<string, unknown>;
     createdAt: number;
 }
+/** One step of a turn, flattened for the archive. */
+export interface PortableStep extends TurnStep {
+    turnId: string;
+}
+/** Everything the portable bundle needs, scoped to one soul/user. */
+export interface PortableDump {
+    entities: Entity[];
+    facts: Fact[];
+    threads: TurnThread[];
+    gaps: Gap[];
+    turns: TurnPair[];
+    steps: PortableStep[];
+    corrections: Correction[];
+}
+/** The three layers of the portability contract (spec/vocabulary.v1 §7). */
+export interface PortableBundle {
+    schemaVersion: number;
+    exportedAt: number;
+    soulId: string;
+    userId: string;
+    /** Human-readable: rules, profile, conclusions, promises, entities, open gaps. */
+    summary: string;
+    /** What the model would see right now. */
+    injection: string;
+    /** One JSON object per line, including raw turns — the source of truth. */
+    archive: string[];
+}
 /** What a recall call may narrow by. Everything is optional. */
 export interface TurnPairSpec {
     soulId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soulbridge",
-  "version": "0.0.103",
+  "version": "0.0.105",
   "description": "A personality layer for any agent: continuity, forgetting, and growth across tools.",
   "license": "Apache-2.0",
   "type": "module",