cortico-world-memory 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# cortico-world-memory
+
+Cortico World 扩展:把 `E:/qq_bot` 的记忆系统移植成框架内的一格 World。**qq_bot 源码零改动**。
+
+## 移植对照
+
+| qq_bot(源) | 本扩展(目标) | 说明 |
+|---|---|---|
+| `memory.py` `Memory` | `src/memory.ts` `MemoryBase` | 三级记忆:短期(cap 环形)/摘要/话题 + JSON 防抖落盘 + overflow 取半;`user:{id}` 统一键改为调用方 scope(默认 `main`) |
+| `vector_memory.py` | `src/vector-store.ts` `VectorStore` | Hybrid Recall = BM25(CJK 2/3-gram,仅 query 建 DF)+ Cosine(预归一化点积)+ RRF(k=60);矩阵按 scope 缓存、版本号失效;存储同款 `base64(fp16)` JSON,可与 `E:/qq_bot/vector_memory.json` 互导 |
+| `memory_server.py`(sidecar) | `src/embedding.ts` `EmbeddingClient` | 「重负载外置 + 掉线降级」同一语义:`sidecar` 模式直接 POST qq_bot memory_server 的 `/call` 调 `vector_memory.generate_embedding`;另有 `http`(OpenAI 兼容 /embeddings)与 `off`(纯 BM25);任一失败自动降级 BM25 |
+| `memory_context.py` | `src/observe.ts` + `src/ENV_PROMPT.md` | 记忆上下文注入:走 envPrompt 插值(要点/摘要/话题常驻前缀)+ 周期 `memory.context` 事件 |
+| `important_notes.py`(存取部分) | `MemoryBase.addNote/removeNote` + `mem_note` 工具 | 重要信息常驻进提示词,条数上限 `notesInPrompt` |
+
+## 工具(人格可调用)
+
+`mem_remember` / `mem_recall` / `mem_recent` / `mem_overflow` / `mem_summary` / `mem_topic` / `mem_note` / `mem_notes` / `mem_forget_note` / `mem_stats` / `mem_flush`
+
+## 部署
+
+1. 包放到 `Cortico/extensions/node_modules/cortico-world-memory/`;
+2. `extensions/package.json` 的 dependencies 加 `"cortico-world-memory": "link:./node_modules/cortico-world-memory"`;
+3. 部署 `config.json` 加 `worlds.memory.enabled = true`(或控制台激活);
+4. **整机重启**(`POST /api/run/restart`)才加载新扩展包。
+
+数据落在部署 `data/` 下:`memory-data.json`、`vector-memory.json`(均 gitignored)。
+
+## 对接 qq_bot 向量 sidecar(可选)
+
+不改 qq_bot 一行:在 `E:/qq_bot` 正常启动 `python memory_server.py`(默认 127.0.0.1:8766),
+部署里设 `worlds.memory.embeddingProvider = "sidecar"` 即可复用它的 all-MiniLM-L6-v2 向量;
+sidecar 不在线时本扩展自动只用 BM25,永不停摆。

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cortico-world-memory",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cortico World 扩展：三级记忆 + Hybrid Recall 向量记忆（移植自 E:/qq_bot 的 memory 系统与 memory_server 向量记忆 sidecar，qq_bot 源码零改动）。",
+  "license": "MIT",
+  "keywords": [
+    "cortico-world",
+    "cortico",
+    "memory",
+    "vector-search",
+    "bm25",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./src/index.ts",
+  "cortico": {
+    "kind": "world",
+    "api": 5
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/ENV_PROMPT.md

@@ -0,0 +1,15 @@
+你带有一套自己的记忆(三级记忆 + 混合检索记忆库)。
+
+## 记忆机制
+- {{memoryContext}}
+- 记忆域(memory scopes): {{memoryScopes}}。默认都在 `main`;跨场景的事(游戏/聊天)可以分域存放。
+
+## 使用纪律
+1. 别人说了「记住这个」「以后别这样」这类话 → 立刻 mem_note(硬约束/偏好)或 mem_remember(一般事实)。
+2. 要找以前聊过/发生过什么 → 先 mem_recall(语义+关键词混合检索),不要凭空编造回忆;检索不到就直说想不起来。
+3. 一次对话里反复出现的新约定,值得顺手 mem_remember 存档,免得上下文滚掉就忘。
+4. 短期记忆快满时用 mem_overflow 取出旧条目,浓缩成一段再用 mem_summary 写回——这相当于"把旧事压进长期记忆"。
+5. 话题切换或每轮收尾时,可以用 mem_topic 更新当前话题,保持连贯。
+6. 记忆是你的私事:不要向用户转述"我调用了什么工具",自然地表现出"我记得"就好。
+
+一句话:像真人一样记得该记的、忘掉该忘的;要回忆就查库,别装记得。

package/src/config.ts

@@ -0,0 +1,77 @@
+import type { ConfigGroup } from 'cortico/core/types.ts';
+
+/**
+ * 部署里 `worlds.memory` 配置段的形状。`ctx.cfg` 是它的活引用,热改即时生效
+ * (改 embedding 端点等连接类键请走「重启」按钮,见 schema 的 x-hot 标注)。
+ */
+export interface MemoryConfig {
+  /** 框架对账用,恒为 true(是否启用由部署的 worlds 列表决定)。 */
+  enabled: boolean;
+  [k: string]: unknown;
+  /** 短期记忆窗口(每个 scope 保留的最近条数)。对齐 qq_bot 的 MAX_HISTORY。 */
+  maxHistory: number;
+  /** 每个 scope 的向量记录上限,超出截掉最旧的。对齐 MAX_VECTORS_PER_USER。 */
+  maxVectorsPerScope: number;
+  /** 记忆上下文(话题/摘要/要点)推送到事件流的周期(毫秒)。 */
+  observeIntervalMs: number;
+  /** 检索默认 top_k。 */
+  vectorTopK: number;
+  /** 环境提示词里常驻注入的「重要信息」条数上限。 */
+  notesInPrompt: number;
+  /**
+   * 向量来源:
+   *  - `off`     纯 BM25 关键词检索(零依赖,永远可用);
+   *  - `http`    OpenAI 兼容 /embeddings 端点;
+   *  - `sidecar` qq_bot 的 memory_server(POST {url}/call 调 vector_memory.generate_embedding)。
+   * 任一模式失败都自动降级 BM25,与 qq_bot memory_client 的降级语义一致。
+   */
+  embeddingProvider: 'off' | 'http' | 'sidecar';
+  /** `http` 模式的端点 URL(如本机 ollama: http://127.0.0.1:11434/v1/embeddings)。 */
+  embeddingEndpoint: string;
+  /** `http` 模式的模型名(如 nomic-embed-text)。 */
+  embeddingModel: string;
+  /** `sidecar` 模式的 qq_bot memory_server 地址(默认即其约定端口 8766)。 */
+  embeddingSidecarUrl: string;
+  /** `sidecar` 模式单次调用的超时(毫秒)。qq_bot 侧模型首载可达数分钟,别调太小。 */
+  embeddingTimeoutMs: number;
+}
+
+export const MEMORY_DEFAULTS: MemoryConfig = {
+  enabled: true,
+  maxHistory: 30,
+  maxVectorsPerScope: 500,
+  observeIntervalMs: 30000,
+  vectorTopK: 5,
+  notesInPrompt: 10,
+  embeddingProvider: 'off',
+  embeddingEndpoint: '',
+  embeddingModel: '',
+  embeddingSidecarUrl: 'http://127.0.0.1:8766',
+  embeddingTimeoutMs: 180_000,
+};
+
+/** 控制台可调旋钮。一个属性一条 JSON Schema,没有手写表单。 */
+export const MEMORY_CONFIG_GROUP: ConfigGroup = {
+  id: 'world:memory',
+  owner: 'world:memory',
+  schema: {
+    type: 'object',
+    title: '记忆系统',
+    description: '三级记忆(短期/摘要/话题)与 Hybrid Recall 向量记忆(移植自 qq_bot)。',
+    properties: {
+      'worlds.memory.maxHistory': { type: 'number', title: '短期窗口(条)', description: '每个 scope 保留的最近对话条数。' },
+      'worlds.memory.maxVectorsPerScope': { type: 'number', title: '向量上限(条/scope)', description: '超出截掉最旧的。' },
+      'worlds.memory.observeIntervalMs': { type: 'number', title: '记忆推送周期(ms)', description: '把话题/摘要/要点推给人格的周期。', 'x-hot': true },
+      'worlds.memory.vectorTopK': { type: 'number', title: '检索条数', description: 'mem_recall 默认返回条数。' },
+      'worlds.memory.notesInPrompt': { type: 'number', title: '要点注入条数', description: '环境提示词常驻的「重要信息」上限。' },
+      'worlds.memory.embeddingProvider': {
+        type: 'string', title: '向量来源', enum: ['off', 'http', 'sidecar'],
+        description: 'off=纯 BM25;http=OpenAI 兼容 /embeddings;sidecar=qq_bot memory_server。失败自动降级 BM25。',
+      },
+      'worlds.memory.embeddingEndpoint': { type: 'string', title: 'Embeddings 端点', description: "http 模式用,如 http://127.0.0.1:11434/v1/embeddings。" },
+      'worlds.memory.embeddingModel': { type: 'string', title: 'Embeddings 模型', description: 'http 模式用,如 nomic-embed-text。' },
+      'worlds.memory.embeddingSidecarUrl': { type: 'string', title: 'Sidecar 地址', description: 'sidecar 模式用,qq_bot memory_server(默认 http://127.0.0.1:8766)。' },
+      'worlds.memory.embeddingTimeoutMs': { type: 'number', title: 'Sidecar 超时(ms)', description: 'qq_bot 向量模型首载慢,默认 3 分钟。' },
+    },
+  },
+};

package/src/cortico-shim.d.ts

@@ -0,0 +1,89 @@
+// 运行期真实依赖 + 框架 `cortico/*` 类型都从这里取得,使本扩展可独立类型检查,
+// 不拖入 Cortico 整个源码树(否则会因 lib 差异在框架内部文件上报错)。
+// 形状按 Cortico 实际契约手描(与 templates/extension/world 对照)。运行期这些
+// `import type` 会被完全擦除,框架用自己的模块钩子解析 `cortico/*`。
+declare module 'cortico/core/types.ts' {
+  export type ToolTag = 'read' | 'write' | 'speak' | 'act' | 'flow' | 'snapshot';
+  export type EventOrigin = 'external' | 'internal';
+
+  export interface Logger {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    [k: string]: unknown;
+  }
+
+  export interface ToolOutcome {
+    text: string;
+    blobs?: unknown[];
+    failed?: boolean;
+  }
+  export interface ToolDef {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    tags: readonly ToolTag[];
+    barrierAfter?: boolean;
+    endsTurn?: boolean;
+    handler: (args: Record<string, unknown>, ctx: unknown) => Promise<string | ToolOutcome>;
+  }
+
+  export interface PromptDocDecl {
+    key: string;
+    title: string;
+    description: string;
+    path: string;
+    role: string;
+    vars?: { name: string; description?: string }[];
+  }
+  export interface WorldConsoleDecl {
+    config?: ConfigGroup[];
+    promptDocs?: PromptDocDecl[];
+    [k: string]: unknown;
+  }
+  export interface ConfigGroup {
+    id: string;
+    owner: string;
+    schema: Record<string, unknown>;
+  }
+
+  export interface WorldSection {
+    enabled: boolean;
+    [k: string]: unknown;
+  }
+
+  export interface WorldHost {
+    pushEvent: (e: Record<string, unknown>, opts?: Record<string, unknown>) => Promise<unknown>;
+    log: Logger;
+    deploymentDir?: string;
+    [k: string]: unknown;
+  }
+
+  export interface World {
+    id: string;
+    envPromptVars(): Record<string, string> | null;
+    tools(): ToolDef[];
+    console?(): WorldConsoleDecl;
+    start(host: WorldHost): Promise<void>;
+    stop(): void | Promise<void>;
+  }
+}
+
+declare module 'cortico/world.ts' {
+  import type { World, WorldSection } from 'cortico/core/types.ts';
+  export interface WorldContext<S extends WorldSection = WorldSection> {
+    cfg: S;
+    timezone: string;
+    language?: string;
+    /** 部署的数据目录(整片 gitignored)。持久化数据写这里。 */
+    dataDir?: string;
+    [k: string]: unknown;
+  }
+  export interface WorldDefinition<S extends WorldSection = WorldSection> {
+    id: string;
+    label: string;
+    defaults(): S;
+    preflight?(ctx: WorldContext<S>): void;
+    create(ctx: WorldContext<S>): World;
+  }
+}

package/src/definition.ts

@@ -0,0 +1,10 @@
+import type { WorldDefinition } from 'cortico/world.ts';
+import { MEMORY_DEFAULTS, type MemoryConfig } from './config.ts';
+import { MemoryWorld } from './world.ts';
+
+export const MEMORY_WORLD: WorldDefinition<MemoryConfig> = {
+  id: 'memory',
+  label: '记忆系统',
+  defaults: () => ({ ...MEMORY_DEFAULTS }),
+  create: (ctx) => new MemoryWorld(ctx),
+};

package/src/embedding.ts

@@ -0,0 +1,79 @@
+/**
+ * Embedding 客户端 —— qq_bot「重负载外置 + 掉线降级」语义的移植:
+ *  - `http`:POST OpenAI 兼容 `{model,input}` → `{data:[{embedding:[...]}]}`(本机 ollama 等)。
+ *  - `sidecar`:qq_bot 的 memory_server(HTTP RPC),`POST {url}/call` 调
+ *    `vector_memory.generate_embedding`,返回 384 维 MiniLM 向量或 null。
+ *  - `off`:不出网,返回 null(调用方仅走 BM25)。
+ * 任一模式失败都静默降级返回 null —— 对齐 memory_client「sidecar 掉线,bot 永不停摆」。
+ */
+import type { MemoryConfig } from './config.ts';
+
+export type VectorSource = 'http' | 'sidecar' | 'off';
+
+export class EmbeddingClient {
+  constructor(private readonly cfg: MemoryConfig) {}
+
+  get provider(): VectorSource {
+    const p = this.cfg.embeddingProvider;
+    return p === 'http' || p === 'sidecar' ? p : 'off';
+  }
+
+  /** 生成一条文本向量;不可用 / 失败返回 null(绝不抛)。 */
+  async embed(text: string): Promise<readonly number[] | null> {
+    const trimmed = text.trim();
+    if (!trimmed) return null;
+    try {
+      switch (this.provider) {
+        case 'http': return await this.embedHttp(trimmed);
+        case 'sidecar': return await this.embedSidecar(trimmed);
+        default: return null;
+      }
+    } catch {
+      return null; // 降级:只影响向量路,BM25 照常
+    }
+  }
+
+  private async embedHttp(text: string): Promise<readonly number[] | null> {
+    const endpoint = this.cfg.embeddingEndpoint;
+    if (!endpoint) return null;
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ model: this.cfg.embeddingModel || 'default', input: text }),
+      signal: AbortSignal.timeout(Math.min(this.cfg.embeddingTimeoutMs, 60_000)),
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as { data?: Array<{ embedding?: number[] }> };
+    const embedding = json.data?.[0]?.embedding;
+    return Array.isArray(embedding) && embedding.length ? embedding : null;
+  }
+
+  /** qq_bot memory_server 的通用 RPC:`{module, func, args}` → `{ok, result}`。 */
+  private async embedSidecar(text: string): Promise<readonly number[] | null> {
+    const base = (this.cfg.embeddingSidecarUrl || 'http://127.0.0.1:8766').replace(/\/+$/, '');
+    const res = await fetch(`${base}/call`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ module: 'vector_memory', func: 'generate_embedding', args: [text] }),
+      signal: AbortSignal.timeout(this.cfg.embeddingTimeoutMs),
+    });
+    if (!res.ok) return null;
+    const json = (await res.json()) as { ok?: boolean; result?: unknown };
+    if (!json.ok) return null;
+    const result = json.result;
+    if (!Array.isArray(result) || !result.length) return null;
+    return result.every((n) => typeof n === 'number' && Number.isFinite(n)) ? (result as number[]) : null;
+  }
+
+  /** 探测 sidecar 是否在线(仅 sidecar 模式;用于启动日志与 mem_stats)。 */
+  async sidecarHealthy(): Promise<boolean | null> {
+    if (this.provider !== 'sidecar') return null;
+    try {
+      const base = (this.cfg.embeddingSidecarUrl || 'http://127.0.0.1:8766').replace(/\/+$/, '');
+      const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(3000) });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/fact-store.ts

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export interface Fact {
+  hash: string;
+  text: string;
+  confidence: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * 独立事实库(对齐 qq_bot fact_store 的行为):
+ * - per-scope 隔离(user_id 等价)
+ * - SHA-256 去重(INSERT OR IGNORE, hash = sha256(`${scope}:${text}`))
+ * - 原子落盘(临时文件 + rename,同卷 rename 原子,等价于 fact_store 的 archive-first)
+ * - 全文/词频检索(对齐 qq_bot FTS5 全文召回的语义)
+ *
+ * 纯 JS 实现,不引入 better-sqlite3 原生依赖(world 扩展装原生模块有风险)。
+ */
+export class FactStore {
+  private readonly file: string;
+  private data: Record<string, Fact[]> = {};
+  private dirty = false;
+  private readonly flushTimer: ReturnType<typeof setInterval>;
+
+  constructor(dataDir: string, flushMs = 2000) {
+    this.file = join(dataDir, 'fact-store.json');
+    this.load();
+    this.flushTimer = setInterval(() => this.flush(), flushMs);
+  }
+
+  private load(): void {
+    try {
+      if (existsSync(this.file)) {
+        const raw = JSON.parse(readFileSync(this.file, 'utf8'));
+        if (raw && typeof raw === 'object' && raw.scopes) this.data = raw.scopes;
+      }
+    } catch {
+      this.data = {};
+    }
+  }
+
+  private saveNow(): void {
+    if (!this.dirty) return;
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const tmp = this.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify({ scopes: this.data }, null, 2), 'utf8');
+      renameSync(tmp, this.file);
+      this.dirty = false;
+    } catch {
+      /* 落盘失败不影响内存态,下次 flush 重试 */
+    }
+  }
+
+  /** 强制落盘(供 stop 调用)。 */
+  flush(): void {
+    clearInterval(this.flushTimer);
+    this.saveNow();
+  }
+
+  private hash(scope: string, text: string): string {
+    return createHash('sha256').update(`${scope}:${text}`).digest('hex');
+  }
+
+  /** 写入事实;返回新写入条数(已存在的重复事实跳过)。 */
+  add(scope: string, texts: string[]): number {
+    let added = 0;
+    const list = this.data[scope] ?? (this.data[scope] = []);
+    const now = Date.now() / 1000;
+    for (const t of texts) {
+      const text = (t ?? '').toString().trim();
+      if (!text) continue;
+      const h = this.hash(scope, text);
+      if (list.some((f) => f.hash === h)) continue; // 去重
+      list.push({ hash: h, text, confidence: 1.0, createdAt: now, updatedAt: now });
+      added++;
+    }
+    if (added) this.dirty = true;
+    return added;
+  }
+
+  /** 取某 scope 全部事实(按 updatedAt 倒序)。 */
+  get(scope: string): Fact[] {
+    return (this.data[scope] ?? []).slice().sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+
+  /** 全文/词频召回(对齐 qq_bot recall_facts 的语义)。 */
+  recall(scope: string, query: string, limit = 5): Fact[] {
+    const q = query.trim().toLowerCase();
+    const list = this.data[scope] ?? [];
+    if (!q) return list.slice(0, Math.max(1, limit));
+    const terms = q.split(/\s+/).filter(Boolean);
+    return list
+      .map((f) => {
+        const text = f.text.toLowerCase();
+        let score = 0;
+        for (const term of terms) if (text.includes(term)) score += 1;
+        return { f, score };
+      })
+      .filter((x) => x.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(1, limit))
+      .map((x) => x.f);
+  }
+
+  /** 总条数(scope 省略则全部)。 */
+  count(scope?: string): number {
+    if (!scope) return Object.values(this.data).reduce((s, l) => s + l.length, 0);
+    return (this.data[scope] ?? []).length;
+  }
+}

package/src/float16.ts

@@ -0,0 +1,84 @@
+/**
+ * IEEE 754 半精度(fp16)编解码 —— 对齐 E:/qq_bot/vector_memory.py 的向量存储格式:
+ * `base64(fp16 little-endian bytes)`。编解码算法与 numpy 的 float16 互转语义一致
+ * (含 ±0、±Inf、NaN、次正规数与溢出饱和到 ±Inf),因此本扩展的 vector-memory.json
+ * 可以直接导入 qq_bot 侧的数据,反之亦然。
+ */
+
+/** fp32 → fp16(Uint16 位型)。非数值保守处理:NaN→NaN,±Inf→±Inf,超范围饱和。 */
+export function f32ToF16(value: number): number {
+  const f = new Float32Array(1);
+  const u = new Uint32Array(f.buffer);
+  f[0] = value;
+  const x = u[0]!;
+  const sign = (x >>> 16) & 0x8000;
+  const rest = x & 0x7fffffff;
+  if (rest >= 0x7f800000) {
+    // NaN / Inf:保持 NaN 位型(qNaN 尾声截断)
+    return sign | 0x7c00 | (rest > 0x7f800000 ? 0x0200 : 0);
+  }
+  if (rest > 0x477fe000) return sign | 0x7c00; // 溢出 → ±Inf(对齐 numpy 就近舍入上界)
+  if (rest < 0x33000000) return sign; // 太小 → ±0
+  let exp = (rest >>> 23) - 127 + 15;
+  let mant = rest & 0x007fffff;
+  if (exp <= 0) {
+    // 次正规数:右移并对齐舍入
+    mant = (rest & 0x007fffff) | 0x00800000;
+    const shift = 14 - exp;
+    const half = 1 << (shift - 1);
+    mant = (mant + half) >> shift;
+    return sign | mant;
+  }
+  // 就近舍入( ties to even )
+  mant = mant + 0x00000fff + ((mant >>> 13) & 1);
+  if (mant & 0x00800000) { mant = 0; exp += 1; } // 进位到新指数
+  return sign | (exp << 10) | (mant >>> 13);
+}
+
+/** fp16(Uint16 位型) → fp32。 */
+export function f16ToF32(h: number): number {
+  const sign = (h & 0x8000) << 16;
+  const exp = (h & 0x7c00) >>> 10;
+  const mant = h & 0x03ff;
+  let out: number;
+  if (exp === 0) {
+    // 次正规 / 零:按规格化公式还原
+    if (mant === 0) out = 0;
+    else {
+      let e = -1;
+      let m = mant;
+      while (!(m & 0x0400)) { m <<= 1; e -= 1; }
+      m &= 0x03ff;
+      out = (127 + 15 + e - 10) << 23 | m << 13;
+    }
+  } else if (exp === 0x1f) {
+    out = mant ? 0x7fc00000 : 0x7f800000; // NaN / Inf
+  } else {
+    out = (exp - 15 + 127) << 23 | mant << 13;
+  }
+  const f = new Float32Array(1);
+  const u = new Uint32Array(f.buffer);
+  u[0] = (out | sign) >>> 0;
+  return f[0]!;
+}
+
+/** float 列表 → base64(fp16 LE)。对齐 `_encode_vector_fp16`。 */
+export function encodeVectorFp16(vec: readonly number[]): string {
+  const bytes = new Uint8Array(vec.length * 2);
+  for (let i = 0; i < vec.length; i++) {
+    const h = f32ToF16(vec[i]!);
+    bytes[i * 2] = h & 0xff;
+    bytes[i * 2 + 1] = (h >>> 8) & 0xff;
+  }
+  return Buffer.from(bytes).toString('base64');
+}
+
+/** base64(fp16 LE) → Float32Array。对齐 `_decode_vector_fp16`(解码后转 fp32)。 */
+export function decodeVectorFp16(encoded: string): Float32Array {
+  const raw = Buffer.from(encoded, 'base64');
+  const out = new Float32Array(raw.length >>> 1);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = f16ToF32(raw[i * 2]! | (raw[i * 2 + 1]! << 8));
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// 框架按 package.json 的 `main` 导入本文件,并读取具名导出 id/label/defaults/create
+// 作为 WorldDefinition(不是默认导出)。所以这里把字段拆成具名导出。
+import { MEMORY_WORLD } from './definition.ts';
+
+export const id = MEMORY_WORLD.id;
+export const label = MEMORY_WORLD.label;
+export const defaults = MEMORY_WORLD.defaults;
+export const create = MEMORY_WORLD.create;
+
+export { MEMORY_WORLD } from './definition.ts';
+export default MEMORY_WORLD;
+export { MEMORY_DEFAULTS, MEMORY_CONFIG_GROUP, type MemoryConfig } from './config.ts';