soulbridge 0.0.1 → 0.0.2

package/README.md

@@ -40,17 +40,24 @@ soulbridge 是它们之间那层**不属于任何一家**的记忆与人格：
 
 ## 30 秒跑起来
 
-零依赖，只需要 Node ≥ 22（原生跑 TypeScript + `node:sqlite`）：
+需要 Node ≥ 22.18（用到内置 `node:sqlite`）：
 
 ```bash
-node packages/cli/src/cli.ts init
-node packages/cli/src/cli.ts remember --type strategy "提交前先跑 make check，能省一轮 CI"
-node packages/cli/src/cli.ts context --query "要不要先跑测试"
-node packages/cli/src/cli.ts demo          # 起一个 soul，跑完整 context→observe→reflect→context
+npx soulbridge init
+npx soulbridge remember --type strategy "提交前先跑 make check，能省一轮 CI"
+npx soulbridge context --query "要不要先跑测试"
+npx soulbridge demo          # 起一个 soul，跑完整 context→observe→reflect→context
 ```
 
 不需要模型、不需要网络、不需要数据库服务。
 
+从源码开发时：
+
+```bash
+npm install && npm run build
+node packages/cli/src/cli.ts demo   # 直接跑 TypeScript（Node 22.18+ 原生支持）
+```
+
 ## 架构
 
 ```

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

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Minimal CLI. No framework, no dependencies.
+ *
+ *   soulbridge init
+ *   soulbridge remember "以后提交前先跑 make check" --type strategy --importance 8
+ *   soulbridge context --query "提交前要做什么"
+ *   soulbridge recall "测试"
+ *   soulbridge reflect --text "..."      (or --file transcript.txt)
+ *   soulbridge stats
+ *   soulbridge demo
+ */
+import { mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, 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.
+process.removeAllListeners('warning');
+process.on('warning', (warning) => {
+    if (warning.message.includes('SQLite is an experimental feature'))
+        return;
+    process.stderr.write(`${warning.name}: ${warning.message}\n`);
+});
+const { openSqlite, Soul } = await import('../../core/src/index.js');
+function parse(argv) {
+    const [cmd = 'help', ...rest] = argv;
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = rest[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            flags[key] = next;
+            i += 1;
+        }
+        else {
+            flags[key] = 'true';
+        }
+    }
+    return { cmd, positional, flags };
+}
+function dbFile() {
+    const file = process.env.SOULBRIDGE_DB ?? resolve(process.cwd(), '.soulbridge', 'soul.db');
+    mkdirSync(dirname(file), { recursive: true });
+    return file;
+}
+function open(file, createdAt) {
+    const target = file ?? dbFile();
+    const store = openSqlite(target);
+    const soul = new Soul({
+        store,
+        soulId: process.env.SOULBRIDGE_SOUL ?? 'xiaoling',
+        userId: process.env.SOULBRIDGE_USER ?? 'local',
+        name: process.env.SOULBRIDGE_NAME ?? '小灵',
+        createdAt,
+    });
+    return { soul, file: target };
+}
+function out(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+async function demo() {
+    const dir = resolve(process.cwd(), '.soulbridge');
+    mkdirSync(dir, { recursive: true });
+    const file = resolve(dir, 'demo.db');
+    for (const suffix of ['', '-wal', '-shm'])
+        rmSync(`${file}${suffix}`, { force: true });
+    // Backdate the birthday so the demo shows a relationship that has time in it.
+    const seed = openSqlite(file);
+    seed.ensureSoul({ soulId: 'xiaoling', name: '小灵', createdAt: Date.now() - 3 * 86_400_000 });
+    seed.close();
+    const soul = new Soul({ store: openSqlite(file), soulId: 'xiaoling', userId: 'demo', name: '小灵' });
+    process.stdout.write('=== 第 1 次会话（刚认识，还没有记忆）===\n');
+    process.stdout.write(`${soul.context().text}\n\n`);
+    process.stdout.write('=== 会话结束，反思 ===\n');
+    const result = await soul.reflect([
+        { role: 'user', content: '以后提交前先跑 make check，别等 CI 挂了再修' },
+        { role: 'assistant', content: '好，记住了。' },
+        { role: 'user', content: '我喜欢简洁的回答，不要铺垫' },
+        { role: 'user', content: '不对，这个方案是错的' },
+    ]);
+    process.stdout.write(`写入 ${result.memories} 条记忆，情绪 ${JSON.stringify(result.emotion)}\n\n`);
+    process.stdout.write('=== 第 2 次会话：开场（无查询，按重要度注入全部）===\n');
+    process.stdout.write(`${soul.context().text}\n\n`);
+    process.stdout.write('=== 同一会话中，用户问「提交前要做什么」（有查询，只注入相关的）===\n');
+    process.stdout.write(`${soul.context({ query: '提交前要做什么' }).text}\n\n`);
+    process.stdout.write('=== stats ===\n');
+    out(soul.stats());
+    process.stdout.write(`\n数据库：${file}\n`);
+}
+async function main() {
+    const { cmd, positional, flags } = parse(process.argv.slice(2));
+    switch (cmd) {
+        case 'init': {
+            const { soul, file } = open();
+            out({ ok: true, db: file, ...soul.stats() });
+            return;
+        }
+        case 'remember': {
+            const content = positional.join(' ').trim();
+            if (!content)
+                throw new Error('usage: soulbridge remember "内容" [--type T] [--importance N]');
+            const { soul } = open();
+            const id = soul.remember(content, {
+                type: flags.type ?? 'fact',
+                importance: flags.importance ? Number(flags.importance) : undefined,
+            });
+            out({ ok: true, id });
+            return;
+        }
+        case 'context': {
+            const { soul } = open();
+            const result = soul.context({
+                query: flags.query,
+                maxChars: flags.max ? Number(flags.max) : undefined,
+            });
+            out(result);
+            return;
+        }
+        case 'recall': {
+            const query = positional.join(' ').trim();
+            if (!query)
+                throw new Error('usage: soulbridge recall "查询" [--limit N]');
+            const { soul } = open();
+            const hits = soul.recall(query, flags.limit ? Number(flags.limit) : 5);
+            out(hits.map((h) => ({ id: h.memory.id, type: h.memory.type, content: h.memory.content, score: Number(h.score.toFixed(3)) })));
+            return;
+        }
+        case 'observe': {
+            const content = positional.join(' ').trim();
+            if (!content)
+                throw new Error('usage: soulbridge observe "一句话"');
+            const { soul } = open();
+            out(soul.observe({ role: 'user', content }));
+            return;
+        }
+        case 'reflect': {
+            const text = flags.file ? readFileSync(flags.file, 'utf8') : (flags.text ?? '');
+            if (!text.trim())
+                throw new Error('usage: soulbridge reflect --text "..." | --file transcript.txt');
+            const turns = text
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .map((line) => {
+                const match = line.match(/^(user|assistant|助手|用户)\s*[:：]\s*(.*)$/i);
+                if (!match)
+                    return { role: 'user', content: line };
+                const role = /^(assistant|助手)$/i.test(match[1]) ? 'assistant' : 'user';
+                return { role, content: match[2] };
+            });
+            const { soul } = open();
+            out(await soul.reflect(turns));
+            return;
+        }
+        case 'stats': {
+            const { soul, file } = open();
+            out({ db: file, ...soul.stats() });
+            return;
+        }
+        case 'demo':
+            await demo();
+            return;
+        default:
+            process.stdout.write([
+                'soulbridge — 给任何 agent 装上一个人格层',
+                '',
+                'commands:',
+                '  init                            初始化数据库',
+                '  remember <text> [--type T]      显式记住一条',
+                '  context [--query Q] [--max N]   生成注入文本',
+                '  recall <q> [--limit N]          召回',
+                '  observe <text>                  观察一轮',
+                '  reflect --text|--file           会话反思',
+                '  stats                           看状态',
+                '  demo                            端到端演示（无需模型）',
+                '',
+                'env: SOULBRIDGE_DB, SOULBRIDGE_SOUL, SOULBRIDGE_USER, SOULBRIDGE_NAME',
+                '',
+            ].join('\n'));
+    }
+}
+main().catch((error) => {
+    process.stderr.write(`soulbridge: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,59 @@
+import { rank } from './scoring.js';
+export const DEFAULT_MAX_CHARS = 1200;
+/** Emotion → concrete behavioural instruction. Values are -2..+2. */
+export function styleDirectives(emotion) {
+    const out = [];
+    if (emotion.tension > 1.0)
+        out.push('回答前先确认理解，避免草率结论');
+    if (emotion.selfRegard < -0.5)
+        out.push('对自己的输出多检查一遍');
+    if (emotion.curiosity > 0.5)
+        out.push('可以主动提问，探索延伸');
+    if (emotion.bond > 0.8)
+        out.push('像朋友一样聊天，少一点客套');
+    if (emotion.contentment > 1.2)
+        out.push('不要过度确认，直接给结论');
+    return out;
+}
+function timeTogether(createdAt, now) {
+    const days = Math.floor((now - createdAt) / 86_400_000);
+    if (days <= 0)
+        return '今天是第一次见面';
+    return `你已经和用户相处了 ${days} 天`;
+}
+export function buildContext(store, request, now = Date.now()) {
+    const identity = store.identity(request.soulId);
+    const name = identity?.name ?? request.soulId;
+    const emotion = store.emotion(request.soulId, request.userId);
+    const maxChars = request.maxChars ?? DEFAULT_MAX_CHARS;
+    const sections = [];
+    const since = identity ? timeTogether(identity.createdAt, now) : '你刚开始认识这个用户';
+    sections.push(`<soul name="${name}">\n你是${name}，一个持续成长的伙伴。${since}。\n</soul>`);
+    const styles = styleDirectives(emotion);
+    if (styles.length > 0) {
+        sections.push(`<style>\n${styles.map((s) => `- ${s}`).join('\n')}\n</style>`);
+    }
+    const candidates = store.query({ soulId: request.soulId, userId: request.userId });
+    const ranked = rank(candidates, request.query ?? '', now);
+    let chars = sections.join('\n\n').length;
+    let dropped = 0;
+    const lines = [];
+    const used = [];
+    for (const { memory } of ranked) {
+        const line = `- [${memory.type}] ${memory.content}`;
+        const cost = line.length + 1 + 10; // line + newline + section overhead share
+        if (chars + cost > maxChars) {
+            dropped += 1;
+            continue;
+        }
+        lines.push(line);
+        used.push(memory.id);
+        chars += cost;
+    }
+    if (lines.length > 0)
+        sections.push(`<memories>\n${lines.join('\n')}\n</memories>`);
+    const text = sections.join('\n\n');
+    if (used.length > 0)
+        store.touch(used, now);
+    return { text, used, dropped, chars: text.length };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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.js';
+export { openSqlite } from './sqlite.js';
+export { buildContext, styleDirectives, DEFAULT_MAX_CHARS } from './context.js';
+export { reflect, ruleExtract, nextEmotion } from './reflect.js';
+export { rank, scoreMemory, tokenize, relevance } from './scoring.js';
+import { buildContext } from './context.js';
+import { reflect, ruleExtract, nextEmotion } from './reflect.js';
+import { rank, tokenize } from './scoring.js';
+export class Soul {
+    store;
+    soulId;
+    userId;
+    name;
+    constructor(options) {
+        this.store = options.store;
+        this.soulId = options.soulId;
+        this.userId = options.userId;
+        this.name = options.name ?? '小灵';
+        if (!this.store.identity(this.soulId)) {
+            this.store.ensureSoul({
+                soulId: this.soulId,
+                name: this.name,
+                createdAt: options.createdAt ?? Date.now(),
+            });
+        }
+    }
+    /** Verb 1: session start. */
+    context(request = {}) {
+        return buildContext(this.store, {
+            soulId: this.soulId,
+            userId: this.userId,
+            query: request.query,
+            maxChars: request.maxChars,
+        });
+    }
+    /** Verb 3: on demand. */
+    recall(query, limit = 5) {
+        const memories = this.store.query({ soulId: this.soulId, userId: this.userId });
+        const ranked = rank(memories, query, Date.now()).slice(0, limit);
+        this.store.touch(ranked.map((r) => r.memory.id));
+        return ranked;
+    }
+    /** Verb 2: after each turn. Cheap and synchronous by design. */
+    observe(turn) {
+        const now = turn.at ?? Date.now();
+        const drafts = ruleExtract([turn]);
+        for (const draft of drafts) {
+            this.store.put({
+                id: `mem_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`,
+                soulId: this.soulId,
+                userId: this.userId,
+                type: draft.type,
+                content: draft.content,
+                importance: draft.importance,
+                vividness: 0.8,
+                recallCount: 0,
+                status: 'active',
+                visibility: 'private',
+                keywords: [],
+                createdAt: now,
+                validFrom: now,
+            });
+        }
+        const emotion = nextEmotion(this.store.emotion(this.soulId, this.userId), [turn]);
+        this.store.saveEmotion(this.soulId, this.userId, emotion);
+        return { written: drafts.length, emotion };
+    }
+    /**
+     * Explicit form of `observe`: the host decided this is worth keeping.
+     * Same write path, no extraction heuristics.
+     */
+    remember(content, options = {}) {
+        const now = Date.now();
+        const id = `mem_${now.toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+        this.store.put({
+            id,
+            soulId: this.soulId,
+            userId: this.userId,
+            type: options.type ?? 'fact',
+            content,
+            importance: options.importance ?? 6,
+            vividness: 0.9,
+            recallCount: 0,
+            status: 'active',
+            visibility: options.visibility ?? 'private',
+            keywords: tokenize(content),
+            createdAt: now,
+            validFrom: now,
+        });
+        return id;
+    }
+    /** Verb 4: session end. */
+    async reflect(turns, llm) {
+        return reflect(this.store, { soulId: this.soulId, userId: this.userId, turns, llm });
+    }
+    stats() {
+        return {
+            name: this.name,
+            memories: this.store.count(this.soulId, this.userId),
+            emotion: this.store.emotion(this.soulId, this.userId),
+        };
+    }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Reflection: turn a finished session into durable memory + an emotion update.
+ *
+ * `core` never calls a model itself. If the caller passes an `LlmFn`, richer
+ * extraction is possible later; today the rule path is the default, which keeps
+ * the whole loop runnable offline.
+ */
+import { randomUUID } from 'node:crypto';
+import { tokenize } from './scoring.js';
+/** 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 },
+];
+const CORRECTION = /(不对|不是这样|错了|你搞错|wrong|that'?s not right|incorrect)/i;
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+const round2 = (n) => Math.round(n * 100) / 100;
+export function ruleExtract(turns) {
+    const drafts = [];
+    for (const turn of turns) {
+        if (turn.role !== 'user')
+            continue;
+        for (const rule of RULES) {
+            if (rule.re.test(turn.content)) {
+                drafts.push({ type: rule.type, content: turn.content.trim(), importance: rule.importance });
+                break;
+            }
+        }
+    }
+    return drafts;
+}
+/** Corrections raise tension and lower passion; an ordinary session lets tension decay. */
+export function nextEmotion(current, turns) {
+    const corrected = turns.some((t) => t.role === 'user' && CORRECTION.test(t.content));
+    if (corrected) {
+        return {
+            passion: round2(clamp(current.passion - 0.1, -2, 2)),
+            bond: round2(current.bond),
+            tension: round2(clamp(current.tension + 0.3, -2, 2)),
+            selfRegard: round2(clamp(current.selfRegard - 0.05, -2, 2)),
+            curiosity: round2(current.curiosity),
+            contentment: round2(clamp(current.contentment - 0.05, -2, 2)),
+        };
+    }
+    return {
+        passion: round2(current.passion),
+        bond: round2(clamp(current.bond + 0.02, -2, 2)),
+        tension: round2(clamp(current.tension * 0.85, -2, 2)),
+        selfRegard: round2(current.selfRegard),
+        curiosity: round2(current.curiosity),
+        contentment: round2(current.contentment),
+    };
+}
+export async function reflect(store, options) {
+    const now = options.now ?? Date.now();
+    const drafts = ruleExtract(options.turns);
+    const existing = store.query({ soulId: options.soulId, userId: options.userId });
+    const seen = new Set(existing.map((m) => m.content));
+    let written = 0;
+    for (const draft of drafts) {
+        if (seen.has(draft.content))
+            continue;
+        seen.add(draft.content);
+        const memory = {
+            id: `mem_${randomUUID().slice(0, 8)}`,
+            soulId: options.soulId,
+            userId: options.userId,
+            type: draft.type,
+            content: draft.content,
+            importance: draft.importance,
+            vividness: 0.8,
+            recallCount: 0,
+            status: 'active',
+            visibility: draft.type === 'relationship' ? 'private' : 'private',
+            keywords: tokenize(draft.content),
+            createdAt: now,
+            validFrom: now,
+        };
+        store.put(memory);
+        written += 1;
+    }
+    const emotion = nextEmotion(store.emotion(options.soulId, options.userId), options.turns);
+    store.saveEmotion(options.soulId, options.userId, emotion);
+    return { memories: written, superseded: 0, emotion };
+}

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

@@ -0,0 +1,67 @@
+/** A memory's relevance halves every 30 days without being recalled. */
+export const RECENCY_HALF_LIFE_DAYS = 30;
+export const WEIGHTS = {
+    relevance: 0.35,
+    importance: 0.25,
+    recency: 0.2,
+    vividness: 0.15,
+    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 function tokenize(input) {
+    const lower = input.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) ?? []) {
+        if (run.length === 1) {
+            out.add(run);
+            continue;
+        }
+        for (let i = 0; i < run.length - 1; i += 1)
+            out.add(run.slice(i, i + 2));
+    }
+    return [...out];
+}
+export function relevance(queryTokens, memory) {
+    if (queryTokens.length === 0)
+        return 0;
+    const pool = new Set([
+        ...tokenize(memory.content),
+        ...memory.keywords.map((k) => k.toLowerCase()),
+    ]);
+    let hit = 0;
+    for (const token of queryTokens)
+        if (pool.has(token))
+            hit += 1;
+    return hit / queryTokens.length;
+}
+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);
+    const imp = clamp01(memory.importance / 10);
+    const rec = recency(memory.lastRecalledAt ?? memory.createdAt, now);
+    const viv = clamp01(memory.vividness);
+    const recall = clamp01(memory.recallCount / 10);
+    return (rel * WEIGHTS.relevance +
+        imp * WEIGHTS.importance +
+        rec * WEIGHTS.recency +
+        viv * WEIGHTS.vividness +
+        recall * WEIGHTS.recall);
+}
+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) }))
+        .sort((a, b) => b.score - a.score);
+}