soulbridge 0.0.1 → 0.0.2

package/packages/core/src/reflect.ts

@@ -1,117 +0,0 @@
-/**
- * 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 type { Emotion, LlmFn, Memory, MemoryType, ReflectResult, Turn } from './types.ts';
-import type { SoulStore } from './store.ts';
-import { tokenize } from './scoring.ts';
-
-interface Draft {
-  type: MemoryType;
-  content: string;
-  importance: number;
-}
-
-interface Rule {
-  re: RegExp;
-  type: MemoryType;
-  importance: number;
-}
-
-/** Cheap, synchronous, no model. Deliberately conservative: false positives cost trust. */
-const RULES: Rule[] = [
-  { 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: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
-const round2 = (n: number) => Math.round(n * 100) / 100;
-
-export function ruleExtract(turns: Turn[]): Draft[] {
-  const drafts: Draft[] = [];
-  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: Emotion, turns: Turn[]): Emotion {
-  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 interface ReflectOptions {
-  soulId: string;
-  userId: string;
-  turns: Turn[];
-  now?: number;
-  /** Reserved for richer extraction; unused in v0. */
-  llm?: LlmFn;
-}
-
-export async function reflect(store: SoulStore, options: ReflectOptions): Promise<ReflectResult> {
-  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: 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/packages/core/src/scoring.ts

@@ -1,87 +0,0 @@
-/**
- * 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 const RECENCY_HALF_LIFE_DAYS = 30;
-
-export const WEIGHTS = {
-  relevance: 0.35,
-  importance: 0.25,
-  recency: 0.2,
-  vividness: 0.15,
-  recall: 0.05,
-} as const;
-
-/**
- * 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: string): string[] {
-  const lower = input.toLowerCase();
-  const out = new Set<string>();
-
-  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: string[], memory: Memory): number {
-  if (queryTokens.length === 0) return 0;
-  const pool = new Set<string>([
-    ...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: number, now: number): number {
-  const days = Math.max(0, (now - reference) / 86_400_000);
-  return Math.pow(0.5, days / RECENCY_HALF_LIFE_DAYS);
-}
-
-const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
-
-export function scoreMemory(memory: Memory, queryTokens: string[], now: number): number {
-  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: Memory[], query: string, now: number): Array<{ memory: Memory; score: number }> {
-  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);
-}

package/packages/core/src/sqlite.ts

@@ -1,202 +0,0 @@
-/**
- * SQLite implementation of SoulStore, using Node's built-in `node:sqlite`.
- * Zero npm dependencies on purpose: `npx soulbridge` must work offline.
- */
-import { DatabaseSync } from 'node:sqlite';
-import { DEFAULT_EMOTION } from './types.ts';
-import type { Emotion, Identity, Memory, QuerySpec } from './types.ts';
-import type { SoulStore } from './store.ts';
-
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS schema_meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);
-CREATE TABLE IF NOT EXISTS souls (
-  soul_id    TEXT PRIMARY KEY,
-  name       TEXT NOT NULL,
-  creator    TEXT,
-  created_at INTEGER NOT NULL
-);
-CREATE TABLE IF NOT EXISTS emotions (
-  soul_id      TEXT NOT NULL,
-  user_id      TEXT NOT NULL,
-  passion      REAL NOT NULL,
-  bond         REAL NOT NULL,
-  tension      REAL NOT NULL,
-  self_regard  REAL NOT NULL,
-  curiosity    REAL NOT NULL,
-  contentment  REAL NOT NULL,
-  PRIMARY KEY (soul_id, user_id)
-);
-CREATE TABLE IF NOT EXISTS memories (
-  id               TEXT PRIMARY KEY,
-  soul_id          TEXT NOT NULL,
-  user_id          TEXT NOT NULL,
-  type             TEXT NOT NULL,
-  content          TEXT NOT NULL,
-  importance       REAL NOT NULL,
-  vividness        REAL NOT NULL,
-  recall_count     INTEGER NOT NULL DEFAULT 0,
-  status           TEXT NOT NULL,
-  visibility       TEXT NOT NULL,
-  keywords         TEXT NOT NULL DEFAULT '[]',
-  created_at       INTEGER NOT NULL,
-  last_recalled_at INTEGER,
-  valid_from       INTEGER,
-  valid_until      INTEGER,
-  superseded_by    TEXT
-);
-CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(soul_id, user_id, status);
-CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(soul_id, created_at DESC);
-`;
-
-type Row = Record<string, unknown>;
-
-function toMemory(row: Row): Memory {
-  return {
-    id: String(row.id),
-    soulId: String(row.soul_id),
-    userId: String(row.user_id),
-    type: row.type as Memory['type'],
-    content: String(row.content),
-    importance: Number(row.importance),
-    vividness: Number(row.vividness),
-    recallCount: Number(row.recall_count),
-    status: row.status as Memory['status'],
-    visibility: row.visibility as Memory['visibility'],
-    keywords: JSON.parse(String(row.keywords ?? '[]')) as string[],
-    createdAt: Number(row.created_at),
-    lastRecalledAt: row.last_recalled_at == null ? undefined : Number(row.last_recalled_at),
-    validFrom: row.valid_from == null ? undefined : Number(row.valid_from),
-    validUntil: row.valid_until == null ? undefined : Number(row.valid_until),
-    supersededBy: row.superseded_by == null ? undefined : String(row.superseded_by),
-  };
-}
-
-export function openSqlite(file: string): SoulStore {
-  const db = new DatabaseSync(file);
-  db.exec('PRAGMA journal_mode = WAL;');
-  db.exec(SCHEMA);
-  db.prepare('INSERT OR REPLACE INTO schema_meta (k, v) VALUES (?, ?)').run('version', '1');
-
-  const stmtPut = db.prepare(`
-    INSERT INTO memories (
-      id, soul_id, user_id, type, content, importance, vividness, recall_count,
-      status, visibility, keywords, created_at, last_recalled_at, valid_from, valid_until, superseded_by
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(id) DO UPDATE SET
-      content = excluded.content,
-      importance = excluded.importance,
-      vividness = excluded.vividness,
-      status = excluded.status,
-      superseded_by = excluded.superseded_by
-  `);
-
-  return {
-    ensureSoul(identity: Identity): void {
-      db.prepare(
-        'INSERT INTO souls (soul_id, name, creator, created_at) VALUES (?, ?, ?, ?) ON CONFLICT(soul_id) DO NOTHING',
-      ).run(identity.soulId, identity.name, identity.creator ?? null, identity.createdAt);
-    },
-
-    identity(soulId: string): Identity | null {
-      const row = db.prepare('SELECT * FROM souls WHERE soul_id = ?').get(soulId) as Row | undefined;
-      if (!row) return null;
-      return {
-        soulId: String(row.soul_id),
-        name: String(row.name),
-        creator: row.creator == null ? undefined : String(row.creator),
-        createdAt: Number(row.created_at),
-      };
-    },
-
-    emotion(soulId: string, userId: string): Emotion {
-      const row = db
-        .prepare('SELECT * FROM emotions WHERE soul_id = ? AND user_id = ?')
-        .get(soulId, userId) as Row | undefined;
-      if (!row) return { ...DEFAULT_EMOTION };
-      return {
-        passion: Number(row.passion),
-        bond: Number(row.bond),
-        tension: Number(row.tension),
-        selfRegard: Number(row.self_regard),
-        curiosity: Number(row.curiosity),
-        contentment: Number(row.contentment),
-      };
-    },
-
-    saveEmotion(soulId: string, userId: string, emotion: Emotion): void {
-      db.prepare(
-        `INSERT INTO emotions (soul_id, user_id, passion, bond, tension, self_regard, curiosity, contentment)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-         ON CONFLICT(soul_id, user_id) DO UPDATE SET
-           passion = excluded.passion, bond = excluded.bond, tension = excluded.tension,
-           self_regard = excluded.self_regard, curiosity = excluded.curiosity,
-           contentment = excluded.contentment`,
-      ).run(
-        soulId,
-        userId,
-        emotion.passion,
-        emotion.bond,
-        emotion.tension,
-        emotion.selfRegard,
-        emotion.curiosity,
-        emotion.contentment,
-      );
-    },
-
-    put(memory: Memory): void {
-      stmtPut.run(
-        memory.id,
-        memory.soulId,
-        memory.userId,
-        memory.type,
-        memory.content,
-        memory.importance,
-        memory.vividness,
-        memory.recallCount,
-        memory.status,
-        memory.visibility,
-        JSON.stringify(memory.keywords),
-        memory.createdAt,
-        memory.lastRecalledAt ?? null,
-        memory.validFrom ?? null,
-        memory.validUntil ?? null,
-        memory.supersededBy ?? null,
-      );
-    },
-
-    query(spec: QuerySpec): Memory[] {
-      const statuses = spec.status ?? ['active'];
-      const placeholders = statuses.map(() => '?').join(', ');
-      const rows = db
-        .prepare(
-          `SELECT * FROM memories
-           WHERE soul_id = ? AND (user_id = ? OR visibility = 'shared') AND status IN (${placeholders})
-           ORDER BY created_at DESC LIMIT ?`,
-        )
-        .all(spec.soulId, spec.userId, ...statuses, spec.limit ?? 500) as Row[];
-
-      const memories = rows.map(toMemory);
-      return spec.types ? memories.filter((m) => spec.types!.includes(m.type)) : memories;
-    },
-
-    touch(ids: string[], now: number = Date.now()): void {
-      const stmt = db.prepare(
-        'UPDATE memories SET recall_count = recall_count + 1, last_recalled_at = ? WHERE id = ?',
-      );
-      for (const id of ids) stmt.run(now, id);
-    },
-
-    count(soulId: string, userId: string): number {
-      const row = db
-        .prepare(
-          "SELECT COUNT(*) AS n FROM memories WHERE soul_id = ? AND (user_id = ? OR visibility = 'shared')",
-        )
-        .get(soulId, userId) as Row;
-      return Number(row.n);
-    },
-
-    close(): void {
-      db.close();
-    },
-  };
-}

package/packages/core/src/store.ts

@@ -1,22 +0,0 @@
-/**
- * The only port. Six methods on purpose: every added method is a storage
- * engine's opinion leaking into the domain.
- */
-import type { 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): void;
-
-  put(memory: Memory): void;
-  /** Active memories visible to `userId` (own private + shared). */
-  query(spec: QuerySpec): Memory[];
-  /** Recall bookkeeping: recallCount++, lastRecalledAt = now. */
-  touch(ids: string[], now?: number): void;
-
-  count(soulId: string, userId: string): number;
-  close(): void;
-}

package/packages/core/src/types.ts

@@ -1,119 +0,0 @@
-/**
- * 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;
-}
-
-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 const DEFAULT_EMOTION: Emotion = {
-  passion: 0.3,
-  bond: 0.3,
-  tension: 0.1,
-  selfRegard: 0.3,
-  curiosity: 0.3,
-  contentment: 0.3,
-};
-
-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;
-}
-
-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;
-}
-
-/** Injected by the caller. `core` never imports a model SDK. */
-export type LlmFn = (prompt: string) => Promise<string> | string;