soulbridge 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023 The Sigstore Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,35 @@
+soulbridge
+Copyright 2026 soulbridge contributors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+--------------------------------------------------------------------------------
+Third-party notices
+--------------------------------------------------------------------------------
+
+Source code bundled in this repository: none.
+
+The repository contains only original code and documentation. Runtime behavior
+relies on Node.js built-in modules (notably `node:sqlite`), which are distributed
+under the Node.js license and are not covered by this repository's license.
+
+Design references (ideas, not code)
+-----------------------------------
+- The four-verb protocol shape (context / observe / recall / reflect) is an
+  original design informed by common agent lifecycle conventions, including the
+  Model Context Protocol's tool conventions.
+- The emotion taxonomy *structure* used by the future affect layer (7 categories,
+  intensity 1–9, polarity) follows the publicly documented structure of the
+  Dalian University of Technology affective lexicon (DUTIR).
+
+  No word list from DUTIR — or from any third-party lexicon — is bundled here.
+  Any lexicon a user supplies remains subject to that user's own licensing
+  obligations. See docs/adr/0006-licensing.md.
+
+--------------------------------------------------------------------------------
+Trademarks
+--------------------------------------------------------------------------------
+
+"Claude", "Cursor", "Codex", "Pi" and other product names are trademarks of their
+respective owners. References to them describe interoperability targets only and
+imply no affiliation or endorsement.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# soulbridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **给任何 agent 装上一个人格层。**
+> A personality layer for any agent — continuity, forgetting, and growth across tools.
+
+**状态：v0.0.1 骨架 · 未发布 · 接口随时会变**
+
+---
+
+## 它解决什么
+
+Claude Code 记得你在 Claude Code 里说过的话，Cursor 不记得，Pi 不记得。
+你的偏好、你的判断、你被纠正过的错——换一个工具，全部归零。
+
+soulbridge 是它们之间那层**不属于任何一家**的记忆与人格：
+
+> 一个 soul，多个宿主；一个人格，持续成长。
+
+## 它不做什么
+
+| 不做 | 为什么 |
+|---|---|
+| agent runtime | 宿主已经免费提供了，再写一遍是重复劳动 |
+| 向量数据库 / RAG 引擎 | 内容是商品，检索可以接现成的 |
+| 云端服务 | 默认全本地，数据不出机器 |
+| “更像人”的叙事营销 | 只承诺可观测的事 |
+
+## 四个动词
+
+宿主只需要在四个时机调用，就完成了接入：
+
+| 动词 | 时机 | 作用 |
+|---|---|---|
+| `context()` | 会话开始 | 注入：身份 + 画像 + 相关记忆 + 表达风格 |
+| `observe(turn)` | 每轮结束 | 观察：写入经历、更新情绪 |
+| `recall(q)` | 需要时 | 召回：按相关性/新旧/重要度/唤醒次数排序 |
+| `reflect(session)` | 会话结束 | 反思：把经历固化成策略与认知 |
+
+详见 [docs/protocol.md](docs/protocol.md)。
+
+## 30 秒跑起来
+
+需要 Node ≥ 22.18（用到内置 `node:sqlite`）：
+
+```bash
+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+ 原生支持）
+```
+
+## 架构
+
+```
+宿主（Claude Code / Pi / DSH / Cursor / Codex）
+        │ hooks + MCP
+        ▼
+packages/core   人格状态 · 评分 · 注入 · 反思   （约 800 行，零依赖）
+        │
+        ▼
+SQLite（默认） / Postgres（可选）
+```
+
+- **人格状态**（身份 / 情绪 / 策略 / 关系 / 特质）：结构化、量小，SQL 就够
+- **内容记忆**（对话片段 / 文档）：v0 用关键词检索，之后可换成向量或外部服务
+
+详见 [docs/architecture.md](docs/architecture.md)。
+
+## 设计文档
+
+| 文档 | 内容 |
+|---|---|
+| [thesis](docs/thesis.md) | 核心命题、三条可证伪预测、四臂实验、放弃条件 |
+| [RFC 0001](docs/rfcs/0001-foundations.md) | 定位、用户、非目标、成功指标、四个动词、接入阶梯 |
+| [ADR 索引](docs/rfcs/README.md) | 11 条已生效的架构决定（定位/语言/存储/依赖/协议/许可/接入/范围/评估/质量） |
+| [protocol.v0](docs/spec/protocol.v0.md) | 四个动词的完整契约：字段、错误码、降级、测试映射 |
+| [quality](docs/quality.md) | 质量模型、九条门禁、五条评审清单 |
+| [references](docs/references.md) | 外部资料的去留与过期判断 |
+
+**规则**：架构级改动必须先有 RFC 或 ADR；聊天里达成的不算决定。
+
+## 为什么值得做
+
+见 [docs/thesis.md](docs/thesis.md)：核心命题、三条可证伪预测、四臂实验设计。
+如果实验否定它，这个项目就该停——**先定好什么情况下放弃，再开始写代码。**
+
+## 隐私
+
+- 默认 SQLite，落在 `~/.soulbridge/soul.db`
+- 零遥测、零上报
+- 记忆可导出、可删除、可迁移
+
+## License
+
+[Apache-2.0](LICENSE) —— 含明确专利授权，便于企业采用。第三方声明见 [NOTICE](NOTICE)。
+
+本项目不捆绑任何第三方源码。未来若引入词库等外部资产，必须单独核查许可（[ADR 0006](docs/adr/0006-licensing.md)）。

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);
+}

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

@@ -0,0 +1,151 @@
+/**
+ * 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.js';
+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);
+`;
+function toMemory(row) {
+    return {
+        id: String(row.id),
+        soulId: String(row.soul_id),
+        userId: String(row.user_id),
+        type: row.type,
+        content: String(row.content),
+        importance: Number(row.importance),
+        vividness: Number(row.vividness),
+        recallCount: Number(row.recall_count),
+        status: row.status,
+        visibility: row.visibility,
+        keywords: JSON.parse(String(row.keywords ?? '[]')),
+        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) {
+    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) {
+            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) {
+            const row = db.prepare('SELECT * FROM souls WHERE soul_id = ?').get(soulId);
+            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, userId) {
+            const row = db
+                .prepare('SELECT * FROM emotions WHERE soul_id = ? AND user_id = ?')
+                .get(soulId, userId);
+            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, userId, emotion) {
+            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) {
+            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) {
+            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);
+            const memories = rows.map(toMemory);
+            return spec.types ? memories.filter((m) => spec.types.includes(m.type)) : memories;
+        },
+        touch(ids, now = Date.now()) {
+            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, userId) {
+            const row = db
+                .prepare("SELECT COUNT(*) AS n FROM memories WHERE soul_id = ? AND (user_id = ? OR visibility = 'shared')")
+                .get(soulId, userId);
+            return Number(row.n);
+        },
+        close() {
+            db.close();
+        },
+    };
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * 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 const DEFAULT_EMOTION = {
+    passion: 0.3,
+    bond: 0.3,
+    tension: 0.1,
+    selfRegard: 0.3,
+    curiosity: 0.3,
+    contentment: 0.3,
+};

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "soulbridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "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"
+  }
+}