memok-ai 核心库

本文适合谁

本站页面概括 **memok-ai** npm 包（SQLite、MemokPipelineConfig、memok-ai/bridge），不是 OpenClaw 安装教程。

• 库集成方 — 你有 Node 服务、队列或 CLI，要把长文/对话写入 SQLite 并做召回、强化。
• 从插件文档跳转来的读者 — 想分清「插件负责什么 / 核心库导出什么」。
• 核心贡献者 — 参与 galaxy8691/memok-ai 本体（流水线、测试、发布）。

建议阅读路径：

1. 集成方：快速上手 → 集成指南 → 常见模式 → 环境变量（浏览）→ 相关链接。
2. OpenClaw 运维：先看本站插件页 /zh/docs/openclaw-plugin 与插件 README；仅在需要 bridge API 形态或 SQLite 语义时回到本页。
3. 贡献者：环境要求 → 安装方法（克隆）→ 贡献者指南。

快速上手（约五分钟）

安装包、对新库执行一次建文件、跑一轮入库。需在进程里提供可用的 OpenAI 兼容密钥（或显式传入 openaiApiKey）。**memok-ai 不会替你加载 .env。**

npm install memok-ai

import { createFreshMemokSqliteFile, articleWordPipeline } from "memok-ai/bridge";

const dbPath = "./data/memok.sqlite";
createFreshMemokSqliteFile(dbPath); // 若库已存在可省略

await articleWordPipeline("你的长文或合并后的对话 …", {
  dbPath,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  openaiBaseUrl: process.env.OPENAI_BASE_URL,
  llmModel: "gpt-4o-mini",
  llmMaxWorkers: 4,
  articleSentencesMaxOutputTokens: 8192,
  coreWordsNormalizeMaxOutputTokens: 32768,
  sentenceMergeMaxCompletionTokens: 2048,
});

接下来：阅读「集成指南」了解导入、召回/反馈与生产配置；「常见集成模式」查看服务骨架示例。

如何选择路径

按目标选一行；第三列指出应优先跟随的文档或仓库。

插件与核心的关系

网关进程加载 memok-ai-openclaw 中的薄扩展；扩展依赖 memok-ai（依赖名常为 memok-ai-core），从 memok-ai-core/bridge 导入稳定 API。SQLite 路径在插件/宿主层配置。无 OpenClaw 时，你的应用直接 import memok-ai 或 memok-ai/bridge。

以下为 Mermaid 源码（可复制到支持 Mermaid 的编辑器或 GitHub 预览中渲染）：

flowchart LR
  subgraph host [OpenClawHost]
    Gateway[GatewayProcess]
  end
  subgraph pluginRepo [memok-ai-openclaw]
    Ext[PluginExtension]
  end
  subgraph corePkg [memok-ai npm]
    Bridge["memok-ai/bridge"]
    Db[(SQLite file)]
  end
  Gateway --> Ext
  Ext --> Bridge
  Bridge --> Db

flowchart LR
  App[你的Node应用] --> Entry["memok-ai 或 memok-ai/bridge"]
  Entry --> Db[(SQLite文件)]

集成指南

主包 memok-ai 导出完整能力；memok-ai/bridge 面向网关类宿主。插件依赖里可能写作 memok-ai-core，npm 发布名仍是 memok-ai。

// 主入口：流水线、SQLite 工具、类型等
import {
  articleWordPipelineV2,
  buildPipelineContext,
} from "memok-ai";

// 网关 / OpenClaw 类宿主常用的稳定子集
import {
  articleWordPipeline,
  dreamingPipeline,
} from "memok-ai/bridge";

典型步骤：npm install memok-ai；选定 dbPath；新库调用一次 createFreshMemokSqliteFile(dbPath)（memok-ai 或 memok-ai/bridge）—创建表、dream_logs、索引；文件已存在会抛错，除非传 { replace: true }；组装 MemokPipelineConfig 并传给 bridge 函数。

memok-ai/bridge 上的 articleWordPipeline、dreamingPipeline 等接收完整 MemokPipelineConfig（或 DreamingPipelineConfig）。若低层流水线只接受 { ctx }，从 memok-ai 导入 buildPipelineContext 并传入 PipelineLlmContext。

import { articleWordPipeline } from "memok-ai/bridge";

await articleWordPipeline(longText, {
  dbPath: "/path/to/memok.sqlite",
  openaiApiKey: process.env.OPENAI_API_KEY!,
  openaiBaseUrl: process.env.OPENAI_BASE_URL,
  llmModel: "gpt-4o-mini",
  llmMaxWorkers: 4,
  articleSentencesMaxOutputTokens: 8192,
  coreWordsNormalizeMaxOutputTokens: 32768,
  sentenceMergeMaxCompletionTokens: 2048,
});

import {
  type MemokPipelineConfig,
  createFreshMemokSqliteFile,
  articleWordPipeline,
  extractMemorySentencesByWordSample,
  applySentenceUsageFeedback,
} from "memok-ai/bridge";

const dbPath = "./data/memok.sqlite";
createFreshMemokSqliteFile(dbPath); // 新库一次；已有可省略，或 { replace: true }

const memok: MemokPipelineConfig = {
  dbPath,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  openaiBaseUrl: process.env.OPENAI_BASE_URL,
  llmModel: "gpt-4o-mini",
  llmMaxWorkers: 4,
  articleSentencesMaxOutputTokens: 8192,
  coreWordsNormalizeMaxOutputTokens: 32768,
  sentenceMergeMaxCompletionTokens: 2048,
};

await articleWordPipeline("长文或合并后的对话 …", memok);

const recall = extractMemorySentencesByWordSample({ ...memok, fraction: 0.2 });
// 用你的 LLM 根据 recall.sentences 组 prompt，再对实际用到的句子 id 调用：

applySentenceUsageFeedback({
  ...memok,
  sentenceIds: recall.sentences.map((s) => s.id),
});

若要在不写 SQLite 的情况下产出 v2 元组，请用 memok-ai 中的 articleWordPipelineV2 与 buildPipelineContext，而不是 articleWordPipeline。

常见集成模式

以下为骨架示例；请自行补全错误重试、日志与 LLM 客户端。返回值形态以上游包为准。

模式 A — 对话增强：会话结束后入库；下次回复前抽样召回；对实际用于回复的记忆句做反馈加权。

import {
  type MemokPipelineConfig,
  articleWordPipeline,
  extractMemorySentencesByWordSample,
  applySentenceUsageFeedback,
} from "memok-ai/bridge";

async function afterSession(memok: MemokPipelineConfig, transcript: string) {
  await articleWordPipeline(transcript, memok);
}

async function beforeReply(memok: MemokPipelineConfig) {
  const recall = extractMemorySentencesByWordSample({ ...memok, fraction: 0.2 });
  // const reply = await yourLlm(buildPrompt(recall.sentences));
  return recall;
}

async function reinforce(memok: MemokPipelineConfig, sentenceIds: number[]) {
  await applySentenceUsageFeedback({ ...memok, sentenceIds });
}

模式 B — 批量文档：对多篇文档循环调用 articleWordPipeline，共用同一 MemokPipelineConfig。

import { articleWordPipeline, type MemokPipelineConfig } from "memok-ai/bridge";

async function indexDocs(memok: MemokPipelineConfig, docs: { id: string; body: string }[]) {
  for (const doc of docs) {
    await articleWordPipeline(doc.body, memok);
  }
}

模式 C — 定时整理：用 cron/队列定时调用 dreamingPipeline；须提供含 dreamLogWarn 的 DreamingPipelineConfig。OpenClaw 插件封装同一函数并自带调度。

import { dreamingPipeline, type DreamingPipelineConfig } from "memok-ai/bridge";

async function runNightlyDreaming(cfg: DreamingPipelineConfig) {
  await dreamingPipeline(cfg);
}

// 示例：生产环境请用平台调度器，勿依赖 setInterval。
// setInterval(() => { void runNightlyDreaming(dreamCfg); }, 24 * 60 * 60 * 1000);

能力与设计理念

memok-ai 是基于 Node.js + TypeScript 的记忆流水线：用 OpenAI 兼容接口处理长文/对话，将结构化单元写入 SQLite，支持召回、强化与 dreaming。

• 一步式文章流水线（article-word-pipeline），稳定 JSON 元组
• SQLite 中 words / normal_words / sentences 及关联表
• dreaming-pipeline：predream + story-word-sentence
• OpenClaw 插件在独立仓库中基于同一 bridge 实现按轮召回与可选定时维护

上游自测：在插件召回/上报流程下，候选记忆在回复中被有效利用的比例可超过 95%；仍取决于模型与采样。

插件在库之上提供：按轮召回、memok_report_used_memory_ids 强化、可选 predream/dreaming 对图做维护型遍历。

与「纯向量库」路线的差异（取舍，不断言检索优劣）：

上游经验：本机 SSD、库不大时，单轮落库 informal 常在约 10² ms、召回 informal 常低于 100 ms——非 SLA；线上可达约千句、十万级关联行量级。

权威说明见：https://github.com/galaxy8691/memok-ai/blob/main/README.zh-CN.md（可对照 https://github.com/galaxy8691/memok-ai/blob/main/README.md）。

环境要求

• Node.js ≥20（建议 LTS）与 npm
• OpenClaw：兼容版本见 https://github.com/galaxy8691/memok-ai-openclaw；本核心仓 package.json 不 pin 网关/API 版本。
• 在本仓首次 npm install 时，better-sqlite3 等原生依赖常占主要耗时，冷启动可需数分钟。

安装方法

1）克隆核心仓做开发

npm install
npm run build
npm test

• npm install — 会执行 prepare → npm run build
• npm run build — 仅 tsc
• npm test — Vitest；设置 OPENAI_API_KEY 时部分测试会调真实 LLM
• npm run ci — Biome + build + test

测试不会自动读 .env。镜像：https://gitee.com/wik20/memok-ai。

2）npm 依赖：https://www.npmjs.com/package/memok-ai

npm install memok-ai

3）OpenClaw 插件：网关相关步骤见 https://github.com/galaxy8691/memok-ai-openclaw 与本站 /zh/docs/openclaw-plugin。

git clone https://github.com/galaxy8691/memok-ai-openclaw.git
cd memok-ai-openclaw
# openclaw plugins install … && openclaw memok setup（见插件 README）

Dreaming

从 memok-ai/bridge 调用 dreamingPipeline，传入 DreamingPipelineConfig：MemokPipelineConfig + 必填 dreamLogWarn + 可选 maxWords、fraction、minRuns、maxRuns。插件侧调度同一函数。

持久化：每次运行（成败）在 dream_logs 追加一行（dream_date、ts、status、log_json）。dreamLogWarn 用于非致命告警（如无法写 dream_logs）；硬错误在记录后仍会抛出。

监控与调试：

1. 将 dream_logs 视为定时维护任务的主健康信号；每个调度窗口后查看最新若干行。
2. 只读库执行 SELECT * FROM dream_logs ORDER BY id DESC LIMIT 5;
3. 失败时看 status = 'error' 与 log_json.error；对比多次 log_json.predream / 故事字段判断合并/衰减是否在推进。
4. 自建调度时应对连续失败与 predream 计数骤降告警；插件用户应对齐上游建议的 cron 并同样查表。

配置优先级说明（OpenClaw 插件）

对 OPENAI_API_KEY、OPENAI_BASE_URL、MEMOK_LLM_MODEL（使用独立插件时）：

• 进程已有环境变量优先
• 插件配置仅补齐缺失值

本核心库从不加载 .env；密钥由进程管理器或网关注入。

环境变量

何时需要关心下表：

• 跑上游测试或本地脚本、用 process.env 拼装配置时。
• OpenClaw 插件进程用 MEMOK_* 填默认项时（见配置优先级）。
• 线上服务仍应优先用显式 MemokPipelineConfig，而非隐式依赖环境表。

谁会读这些变量？

1. OpenClaw 插件进程 — 组装配置时可用 MEMOK_* 补缺
2. 本仓库测试与旧路径 — 未显式传配置对象时可能读 process.env
3. 库集成方 — 生产不应依赖下表；应显式构造 MemokPipelineConfig

各阶段模型名等见源码 resolveModel 等辅助说明。

性能与调优（定性）

下列为实践向说明，无固定 SLA；请在自家环境实测。

贡献者指南

针对核心仓库（非插件）的入门流程：

1. 克隆 galaxy8691/memok-ai，使用 Node 20+。
2. npm install 后执行 npm run ci 再开 PR。
3. 仅在需要跑会调远程模型的测试时设置 OPENAI_API_KEY（见 CONTRIBUTING.md）。
4. 若跳过 install 钩子，改 src/ 后执行 npm run build。

无 memok-ai 独立 dev CLI。openclaw memok setup 等属于网关，请以 openclaw --help 与插件 README 为准。

贡献说明：https://github.com/galaxy8691/memok-ai/blob/main/CONTRIBUTING.md

相关链接

• 官网: https://www.memok-ai.com/
• 本站 OpenClaw 插件文档: /zh/docs/openclaw-plugin
• English README: https://github.com/galaxy8691/memok-ai/blob/main/README.md
• 简体中文 README: https://github.com/galaxy8691/memok-ai/blob/main/README.zh-CN.md
• npm 包: https://www.npmjs.com/package/memok-ai
• OpenClaw 插件仓库: https://github.com/galaxy8691/memok-ai-openclaw
• Gitee 镜像: https://gitee.com/wik20/memok-ai