soulbridge 0.0.21 → 0.0.26

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

@@ -8,8 +8,9 @@ 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, isCorrection, correctionRule } from './reflect.ts';
-export { rank, scoreMemory, tokenize, relevance } from './scoring.ts';
+export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule, detectCorrection, isQuestion, } from './reflect.ts';
+export type { CorrectionLayer, CorrectionSignal, CorrectionVerdict } from './reflect.ts';
+export { rank, scoreMemory, tokenize, relevance, bm25, buildCorpusStats } from './scoring.ts';
 export * from './affect/index.ts';
 export { measureStyle } from './style/measure.ts';
 export type { StyleMetrics } from './style/measure.ts';
@@ -17,7 +18,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, Visibility } from './types.ts';
+import type { AffectSignal, ContextRequest, Correction, Memory, ContextResult, Emotion, LlmFn, MemoryType, ObserveResult, ReflectResult, ScoredMemory, Turn, TurnPair, Visibility } from './types.ts';
 import type { SoulStore } from './store.ts';
 import type { AffectAnalyzer } from './affect/port.ts';
 export { gateDrafts } from './reflect.ts';
@@ -85,6 +86,22 @@ export declare class Soul {
         rule?: string;
     }): string;
     corrections(limit?: number): Correction[];
+    /**
+     * Store one exchange (RFC 0007). Idempotent on `(sessionId, turn)`: a repeat is
+     * ignored by the store, so this returns nothing — there is no id worth handing
+     * back that would also be correct on a repeat.
+     */
+    recordTurnPair(input: {
+        sessionId: string;
+        turn: number;
+        userText: string;
+        assistantText: string;
+        at?: number;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /** Recall exchanges, scored against `query` when it is non-empty. */
+    recallTurnPairs(query: string, limit?: number): TurnPair[];
+    countTurnPairs(): number;
     /** Verb 3: on demand. */
     recall(query: string, limit?: number): ScoredMemory[];
     /** Pure analysis, no storage. Async because the analyzer may call a model. */

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

@@ -7,8 +7,8 @@
 export * from './types.js';
 export { openSqlite, SCHEMA_VERSION, AFFECT_RETENTION_MS, DbNewerThanBinaryError } from './sqlite.js';
 export { buildContext, styleDirectives, DEFAULT_MAX_CHARS, AFFECT_BUDGET, AFFECT_WINDOW_MS, } from './context.js';
-export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule } from './reflect.js';
-export { rank, scoreMemory, tokenize, relevance } from './scoring.js';
+export { reflect, ruleExtract, nextEmotion, isCorrection, correctionRule, detectCorrection, isQuestion, } from './reflect.js';
+export { rank, scoreMemory, tokenize, relevance, bm25, buildCorpusStats } from './scoring.js';
 export * from './affect/index.js';
 export { measureStyle } from './style/measure.js';
 export * from './storage/config.js';
@@ -107,6 +107,38 @@ export class Soul {
     corrections(limit = 20) {
         return this.store.recentCorrections(this.soulId, this.userId, limit);
     }
+    /**
+     * Store one exchange (RFC 0007). Idempotent on `(sessionId, turn)`: a repeat is
+     * ignored by the store, so this returns nothing — there is no id worth handing
+     * back that would also be correct on a repeat.
+     */
+    recordTurnPair(input) {
+        const at = input.at ?? Date.now();
+        this.store.putTurnPair({
+            id: `tp_${at.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+            soulId: this.soulId,
+            userId: this.userId,
+            sessionId: input.sessionId,
+            turn: input.turn,
+            at,
+            userText: input.userText,
+            assistantText: input.assistantText,
+            metadata: input.metadata ?? {},
+            createdAt: at,
+        });
+    }
+    /** Recall exchanges, scored against `query` when it is non-empty. */
+    recallTurnPairs(query, limit = 5) {
+        return this.store.recallTurnPairs({
+            soulId: this.soulId,
+            userId: this.userId,
+            query,
+            limit,
+        });
+    }
+    countTurnPairs() {
+        return this.store.countTurnPairs(this.soulId, this.userId);
+    }
     /** Verb 3: on demand. */
     recall(query, limit = 5) {
         const memories = this.store.query({ soulId: this.soulId, userId: this.userId });

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

@@ -30,6 +30,26 @@ export declare const RULES: Rule[];
 export declare function isCorrection(text: string): boolean;
 /** Which marker matched, for statistics; null when the turn is not a correction. */
 export declare function correctionRule(text: string): string | null;
+export type CorrectionLayer = 'rule' | 'structural' | 'none';
+export type CorrectionSignal = 'negation' | 'replacement' | 'meta';
+export interface CorrectionVerdict {
+    isCorrection: boolean;
+    layer: CorrectionLayer;
+    /** L1 命中的词，或 L2 的信号名；便于统计"为什么记/为什么没记" */
+    marker: string | null;
+}
+/**
+ * L1 + L2 correction detection.
+ *
+ * L1: explicit markers, high precision. L2: structure — a negator/replacement/meta
+ * marker aimed at what the previous reply claimed. L2 only runs when a previous
+ * reply exists, and negation additionally requires ≥2 shared bigrams, so a bare
+ * "不行" about the weather is not mistaken for a correction.
+ *
+ * What this deliberately does NOT do: judge "是否真的不同意" — that needs a model.
+ * 有否定 + 指向上一轮 只能说明"这是候选"，不能说明"用户是对的"。
+ */
+export declare function detectCorrection(text: string, previousReply?: string): CorrectionVerdict;
 /** Types an extractor may produce; episodic/relationship are host-local. */
 export declare const EXTRACTABLE_TYPES: MemoryType[];
 export declare const MAX_CONTENT_CHARS = 500;
@@ -44,6 +64,13 @@ export declare function gateDrafts(drafts: Draft[]): {
     accepted: Draft[];
     rejected: DraftRejection[];
 };
+/**
+ * A question is not a statement to remember.
+ *
+ * Measured case: "我们这个记忆会记住日常生活吗？" was stored as a fact because a
+ * trigger word matched before anything looked at the sentence type.
+ */
+export declare function isQuestion(text: string): boolean;
 export declare function ruleExtract(turns: Turn[]): Draft[];
 /** Corrections raise tension and lower passion; an ordinary session lets tension decay. */
 export declare function nextEmotion(current: Emotion, turns: Turn[]): Emotion;

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

@@ -84,6 +84,68 @@ export function correctionRule(text) {
     const match = CORRECTION.exec(text);
     return match ? match[0] : null;
 }
+/**
+ * A-not-A questions and fixed positive words contain a negator but negate nothing.
+ * Without these exceptions the structural layer fires on half of ordinary questions
+ * (是不是 / 可不可以 / 不错 / 不断 / 算不算).
+ */
+const NEGATION_EXEMPT = /是不是|可不可以|有没有|要不要|对不对|好不好|算不算|是否可以|不错|不断|不仅|不但|不过|不只是/g;
+const NEGATOR = /[不没别]/;
+/** Replacement: the user supplies an alternative instead of denying. */
+const REPLACEMENT = /我想的是|我的意思是|应该是|应该用|改用|换成|不是[^。；]{0,20}而是/;
+/** Meta: the user refers to what the assistant just did. */
+const META = /你刚才|你上一步|你上次|你前面|刚才那/;
+function sharedBigrams(a, b) {
+    const grams = (s) => {
+        const lower = s.toLowerCase();
+        const out = new Set();
+        for (const word of lower.match(/[a-z0-9_]{2,}/g) ?? [])
+            out.add(word);
+        for (const run of lower.match(/[\u4e00-\u9fa5]+/g) ?? []) {
+            for (let i = 0; i < run.length - 1; i += 1)
+                out.add(run.slice(i, i + 2));
+        }
+        return out;
+    };
+    const left = grams(a);
+    const right = grams(b);
+    let hit = 0;
+    for (const g of left)
+        if (right.has(g))
+            hit += 1;
+    return hit;
+}
+/**
+ * L1 + L2 correction detection.
+ *
+ * L1: explicit markers, high precision. L2: structure — a negator/replacement/meta
+ * marker aimed at what the previous reply claimed. L2 only runs when a previous
+ * reply exists, and negation additionally requires ≥2 shared bigrams, so a bare
+ * "不行" about the weather is not mistaken for a correction.
+ *
+ * What this deliberately does NOT do: judge "是否真的不同意" — that needs a model.
+ * 有否定 + 指向上一轮 只能说明"这是候选"，不能说明"用户是对的"。
+ */
+export function detectCorrection(text, previousReply) {
+    const l1 = CORRECTION.exec(text);
+    if (l1)
+        return { isCorrection: true, layer: 'rule', marker: l1[0] };
+    if (!previousReply || previousReply.length === 0) {
+        return { isCorrection: false, layer: 'none', marker: null };
+    }
+    const stripped = text.replace(NEGATION_EXEMPT, ' ');
+    if (NEGATOR.test(stripped) && sharedBigrams(text, previousReply) >= 2) {
+        return { isCorrection: true, layer: 'structural', marker: 'negation' };
+    }
+    const replacement = REPLACEMENT.exec(text);
+    if (replacement)
+        return { isCorrection: true, layer: 'structural', marker: 'replacement' };
+    const meta = META.exec(text);
+    if (meta && (NEGATOR.test(stripped) || /[?？]/.test(text))) {
+        return { isCorrection: true, layer: 'structural', marker: 'meta' };
+    }
+    return { isCorrection: false, layer: 'none', marker: null };
+}
 const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
 const round2 = (n) => Math.round(n * 100) / 100;
 /** Types an extractor may produce; episodic/relationship are host-local. */
@@ -121,11 +183,25 @@ export function gateDrafts(drafts) {
     }
     return { accepted, rejected };
 }
+/**
+ * A question is not a statement to remember.
+ *
+ * Measured case: "我们这个记忆会记住日常生活吗？" was stored as a fact because a
+ * trigger word matched before anything looked at the sentence type.
+ */
+export function isQuestion(text) {
+    const trimmed = text.trim();
+    if (trimmed.endsWith('？') || trimmed.endsWith('?'))
+        return true;
+    return /(吗|呢)[。.!！~～]?$/.test(trimmed);
+}
 export function ruleExtract(turns) {
     const drafts = [];
     for (const turn of turns) {
         if (turn.role !== 'user')
             continue;
+        if (isQuestion(turn.content))
+            continue;
         for (const rule of RULES) {
             if (!rule.match(turn.content))
                 continue;

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

@@ -5,6 +5,15 @@
  *
  * The weights are a claim, not a truth: changing them changes behaviour, so they
  * live here (one place) and are covered by tests.
+ *
+ * relevance 有两种算法：
+ *   - `relevance()`：命中比例。只看"命中了几个 query 词"，不看稀有度、不看长度。
+ *   - `bm25()`：IDF + 长度归一化 + 词频饱和。
+ *
+ * rank() 用 bm25。原因（真机 60 条记忆 / 298 条真实 query 实测）：
+ *   旧算法下，一条 18202 字的聊天记录在 85% 的 query 里进 top3，top1 平均 12150 字；
+ *   换 bm25 后降到 17%，top1 平均 1294 字。文档长度在这个库里差三个数量级
+ *   （4 字 ~ 18202 字），长度归一化是决定性的——这一点在长度均匀的语料上测不出来。
  */
 import type { Memory } from './types.ts';
 /** A memory's relevance halves every 30 days without being recalled. */
@@ -16,14 +25,30 @@ export declare const WEIGHTS: {
     readonly vividness: 0.15;
     readonly recall: 0.05;
 };
+/** BM25 constants. k1 = term-frequency saturation, b = length normalization. */
+export declare const BM25_K1 = 1.5;
+export declare const BM25_B = 0.75;
 /**
  * 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;
+/** Corpus statistics BM25 needs. Must be built over the candidate set, not one memory. */
+export interface CorpusStats {
+    idf: Map<string, number>;
+    avgdl: number;
+}
+/** Build idf / average length over a batch of tokenized documents. Call once per query. */
+export declare function buildCorpusStats(docs: string[][]): CorpusStats;
+/** BM25 over pre-tokenized document tokens. Length normalization is why this replaced plain recall. */
+export declare function bm25(tokens: string[], docTokens: string[], stats: CorpusStats): number;
 export declare function recency(reference: number, now: number): number;
-export declare function scoreMemory(memory: Memory, queryTokens: string[], now: number): number;
+/**
+ * @param relOverride 归一化到 0–1 的相关性。rank() 传 BM25 的归一化值；
+ *                    省略时退回旧的命中比例，保持单独调用的行为不变。
+ */
+export declare function scoreMemory(memory: Memory, queryTokens: string[], now: number, relOverride?: number): number;
 export declare function rank(memories: Memory[], query: string, now: number): Array<{
     memory: Memory;
     score: number;

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

@@ -7,6 +7,9 @@ export const WEIGHTS = {
     vividness: 0.15,
     recall: 0.05,
 };
+/** BM25 constants. k1 = term-frequency saturation, b = length normalization. */
+export const BM25_K1 = 1.5;
+export const BM25_B = 0.75;
 /**
  * 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.
@@ -26,6 +29,10 @@ export function tokenize(input) {
     }
     return [...out];
 }
+/** Token list of one memory, duplicates kept (BM25 needs term frequency). */
+function memoryTokens(memory) {
+    return [...tokenize(memory.content), ...memory.keywords.map((k) => k.toLowerCase())];
+}
 export function relevance(queryTokens, memory) {
     if (queryTokens.length === 0)
         return 0;
@@ -39,13 +46,55 @@ export function relevance(queryTokens, memory) {
             hit += 1;
     return hit / queryTokens.length;
 }
+/** Build idf / average length over a batch of tokenized documents. Call once per query. */
+export function buildCorpusStats(docs) {
+    const df = new Map();
+    let totalLen = 0;
+    for (const tokens of docs) {
+        totalLen += tokens.length;
+        for (const token of new Set(tokens))
+            df.set(token, (df.get(token) ?? 0) + 1);
+    }
+    const n = Math.max(1, docs.length);
+    const idf = new Map();
+    for (const [token, count] of df) {
+        // +1 keeps idf positive so a shared rare token never becomes a penalty.
+        idf.set(token, Math.log((n + 1) / (count + 1)) + 1);
+    }
+    return { idf, avgdl: totalLen / n };
+}
+/** BM25 over pre-tokenized document tokens. Length normalization is why this replaced plain recall. */
+export function bm25(tokens, docTokens, stats) {
+    if (tokens.length === 0)
+        return 0;
+    if (docTokens.length === 0)
+        return 0;
+    const tf = new Map();
+    for (const token of docTokens)
+        tf.set(token, (tf.get(token) ?? 0) + 1);
+    const dl = docTokens.length;
+    const norm = 1 - BM25_B + (BM25_B * dl) / Math.max(1, stats.avgdl);
+    let score = 0;
+    for (const token of new Set(tokens)) {
+        const f = tf.get(token) ?? 0;
+        if (f === 0)
+            continue;
+        const idf = stats.idf.get(token) ?? 1;
+        score += (idf * (f * (BM25_K1 + 1))) / (f + BM25_K1 * norm);
+    }
+    return score;
+}
 export function recency(reference, now) {
     const days = Math.max(0, (now - reference) / 86_400_000);
     return Math.pow(0.5, days / RECENCY_HALF_LIFE_DAYS);
 }
 const clamp01 = (n) => Math.min(1, Math.max(0, n));
-export function scoreMemory(memory, queryTokens, now) {
-    const rel = relevance(queryTokens, memory);
+/**
+ * @param relOverride 归一化到 0–1 的相关性。rank() 传 BM25 的归一化值；
+ *                    省略时退回旧的命中比例，保持单独调用的行为不变。
+ */
+export function scoreMemory(memory, queryTokens, now, relOverride) {
+    const rel = relOverride ?? relevance(queryTokens, memory);
     const imp = clamp01(memory.importance / 10);
     const rec = recency(memory.lastRecalledAt ?? memory.createdAt, now);
     const viv = clamp01(memory.vividness);
@@ -60,8 +109,19 @@ export function rank(memories, query, now) {
     const tokens = tokenize(query);
     // A query is a selection: with one, a memory that shares no token is noise,
     // no matter how important it is. Without one (session start), rank by weight alone.
-    const pool = tokens.length === 0 ? memories : memories.filter((m) => relevance(tokens, m) > 0);
-    return pool
-        .map((memory) => ({ memory, score: scoreMemory(memory, tokens, now) }))
+    if (tokens.length === 0) {
+        return memories
+            .map((memory) => ({ memory, score: scoreMemory(memory, tokens, now) }))
+            .sort((a, b) => b.score - a.score);
+    }
+    const stats = buildCorpusStats(memories.map(memoryTokens));
+    const scored = memories.map((memory) => ({ memory, raw: bm25(tokens, memoryTokens(memory), stats) }));
+    const best = scored.reduce((max, s) => Math.max(max, s.raw), 0);
+    if (best <= 0)
+        return [];
+    // Normalize to 0–1 so the weighted sum below keeps its original scale.
+    return scored
+        .filter((s) => s.raw > 0)
+        .map(({ memory, raw }) => ({ memory, score: scoreMemory(memory, tokens, now, raw / best) }))
         .sort((a, b) => b.score - a.score);
 }

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

@@ -1,6 +1,6 @@
 import { DatabaseSync } from 'node:sqlite';
 import type { SoulStore } from './store.ts';
-export declare const SCHEMA_VERSION = 2;
+export declare const SCHEMA_VERSION = 4;
 export declare const AFFECT_RETENTION_MS: number;
 export declare class DbNewerThanBinaryError extends Error {
     readonly code = "DB_NEWER_THAN_BINARY";

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

@@ -9,7 +9,10 @@
 import { copyFileSync, existsSync } from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
 import { DEFAULT_EMOTION } from './types.js';
-export const SCHEMA_VERSION = 2;
+import { bm25, buildCorpusStats, tokenize } from './scoring.js';
+export const SCHEMA_VERSION = 4;
+/** How many recent pairs are considered before scoring. Bounded so recall stays O(candidates). */
+const RECALL_CANDIDATES = 500;
 export const AFFECT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 const BUSY_TIMEOUT_MS = 5000;
 const WRITE_ATTEMPTS = 3;
@@ -87,6 +90,22 @@ CREATE TABLE IF NOT EXISTS corrections (
   device_id      TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_corrections ON corrections(soul_id, user_id, at DESC);
+CREATE TABLE IF NOT EXISTS turn_pairs (
+  id             TEXT PRIMARY KEY,
+  soul_id        TEXT NOT NULL,
+  user_id        TEXT NOT NULL,
+  session_id     TEXT NOT NULL,
+  turn           INTEGER NOT NULL,
+  at             INTEGER NOT NULL,
+  user_text      TEXT NOT NULL,
+  assistant_text TEXT NOT NULL,
+  metadata_json  TEXT NOT NULL DEFAULT '{}',
+  created_at     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_turn_pairs_scope ON turn_pairs(soul_id, user_id, at DESC);
+-- Idempotency: one exchange per (session, turn). A repeat is ignored, not merged.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_turn_pairs_turn
+  ON turn_pairs(soul_id, user_id, session_id, turn);
 `;
 const sleepSync = (ms) => {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -348,11 +367,77 @@ export function openSqlite(file) {
                 .get(soulId, userId);
             return Number(row.n);
         },
+        putTurnPair(pair) {
+            // INSERT OR IGNORE + the unique index is the whole idempotency story:
+            // one exchange per (session, turn), repeats are dropped, never merged.
+            withRetry(() => db
+                .prepare(`INSERT OR IGNORE INTO turn_pairs
+               (id, soul_id, user_id, session_id, turn, at, user_text, assistant_text,
+                metadata_json, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(pair.id, pair.soulId, pair.userId, pair.sessionId, pair.turn, pair.at, pair.userText, pair.assistantText, JSON.stringify(pair.metadata), pair.createdAt));
+        },
+        recallTurnPairs(spec) {
+            // No cap by default: every related exchange is returned (bounded only by
+            // RECALL_CANDIDATES, which limits rows read, not rows injected).
+            const limit = spec.limit ?? RECALL_CANDIDATES;
+            const rows = db
+                .prepare(`SELECT * FROM turn_pairs
+           WHERE soul_id = ? AND user_id = ? AND at >= ?
+           ORDER BY at DESC LIMIT ?`)
+                .all(spec.soulId, spec.userId, spec.since ?? 0, Math.max(limit, RECALL_CANDIDATES));
+            const pairs = rows.map(rowToTurnPair);
+            const query = spec.query?.trim();
+            if (!query)
+                return pairs.slice(0, limit);
+            const qTokens = tokenize(query);
+            if (qTokens.length === 0)
+                return pairs.slice(0, limit);
+            const docTokens = pairs.map(pairTokens);
+            const stats = buildCorpusStats(docTokens);
+            return pairs
+                .map((pair, i) => ({ pair, score: bm25(qTokens, docTokens[i], stats) }))
+                .filter((scored) => scored.score > 0)
+                .sort((a, b) => b.score - a.score || b.pair.at - a.pair.at)
+                .slice(0, limit)
+                .map((scored) => scored.pair);
+        },
+        countTurnPairs(soulId, userId) {
+            const row = db
+                .prepare('SELECT COUNT(*) AS n FROM turn_pairs WHERE soul_id = ? AND user_id = ?')
+                .get(soulId, userId);
+            return Number(row.n);
+        },
         close() {
             db.close();
         },
     };
 }
+/** Tokens of one exchange. Both sides are searchable; neither is weighted. */
+function pairTokens(pair) {
+    return [...tokenize(pair.userText), ...tokenize(pair.assistantText)];
+}
+function rowToTurnPair(row) {
+    let metadata = {};
+    try {
+        metadata = JSON.parse(String(row.metadata_json ?? '{}'));
+    }
+    catch {
+        metadata = {};
+    }
+    return {
+        id: String(row.id),
+        soulId: String(row.soul_id),
+        userId: String(row.user_id),
+        sessionId: String(row.session_id),
+        turn: Number(row.turn),
+        at: Number(row.at),
+        userText: String(row.user_text),
+        assistantText: String(row.assistant_text),
+        metadata,
+        createdAt: Number(row.created_at),
+    };
+}
 function rowToMemory(row) {
     return {
         id: String(row.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, Identity, Memory, QuerySpec } from './types.ts';
+import type { AffectSignal, Correction, Emotion, Identity, Memory, QuerySpec, TurnPair, TurnPairSpec } from './types.ts';
 export interface SoulStore {
     ensureSoul(identity: Identity): void;
     identity(soulId: string): Identity | null;
@@ -11,6 +11,14 @@ export interface SoulStore {
     put(memory: Memory): void;
     /** Active, non-deleted memories visible to `userId` (own private + shared). */
     query(spec: QuerySpec): Memory[];
+    /**
+     * Store one exchange. Idempotent on `(soul, user, session, turn)`: a repeat is
+     * ignored, never merged — the original text is immutable (RFC 0007).
+     */
+    putTurnPair(pair: TurnPair): void;
+    /** Exchanges visible to `userId`; scored against `spec.query` when given. */
+    recallTurnPairs(spec: TurnPairSpec): TurnPair[];
+    countTurnPairs(soulId: string, userId: string): number;
     /** Recall bookkeeping: recallCount++, lastRecalledAt = now. */
     touch(ids: string[], now?: number): void;
     /**

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

@@ -40,6 +40,36 @@ export interface Identity {
     creator?: string;
     createdAt: number;
 }
+/**
+ * One exchange: what the user said and what the assistant answered.
+ * The unit of memory (RFC 0007). Both sides are original text, never truncated
+ * here — injection drops a whole pair rather than cutting one in half.
+ */
+export interface TurnPair {
+    id: string;
+    soulId: string;
+    userId: string;
+    /** Host session id. Together with `turn` it makes writes idempotent. */
+    sessionId: string;
+    turn: number;
+    /** When the user message arrived. */
+    at: number;
+    userText: string;
+    assistantText: string;
+    /** Open container for fields not decided yet (briefs/0010 §8). */
+    metadata: Record<string, unknown>;
+    createdAt: number;
+}
+/** What a recall call may narrow by. Everything is optional. */
+export interface TurnPairSpec {
+    soulId: string;
+    userId: string;
+    /** Text to score against. Empty means "no query": rank by recency only. */
+    query?: string;
+    limit?: number;
+    /** Only pairs at or after this timestamp. */
+    since?: number;
+}
 /** Six dimensions, each -2..+2. Baseline is slightly positive. */
 export interface Emotion {
     passion: number;

package/package.json

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