# ai-memory-engine

**Repository Path**: work-soho/ai-memory-engine

## Basic Information

- **Project Name**: ai-memory-engine
- **Description**: 类人脑记忆系统
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Memory Engine

使用 Node.js JavaScript 与 SQLite 的本地长期记忆引擎，提供嵌入 SDK 和中文管理后台。

## 启动

要求 Node.js 22.17 或更高版本；当前使用内置 `node:sqlite`，Node.js 22 会显示实验特性提示。

```sh
npm install
npm start
```

浏览器打开 `http://127.0.0.1:3210`，首次初始化账号和密码均为 **admin**。密码以 scrypt 哈希保存，重启不会覆盖已经修改的密码。

PowerShell 如禁止执行 `npm.ps1`，使用 `npm.cmd install` 与 `npm.cmd start`。

可通过 `MEMORY_DATA_DIR`、`MEMORY_ADMIN_USERNAME`、`MEMORY_ADMIN_PASSWORD` 配置数据目录和首次凭据；`MEMORY_MODEL_DIR` 设置模型资源根目录，默认使用数据目录下的 `models/`；`PORT` 设置本地 HTTP 端口。数据默认为当前目录的 `data/`，不会提交到源码仓库。

## SDK

```js
import { createMemoryEngine } from './src/index.js';

const engine = await createMemoryEngine({ dataDir: './data' });
try {
  const request = await engine.remember({
    content: '项目使用 SQLite 保存长期记忆。',
    source: { type: 'user_statement', id: 'message-1' },
  });
  await engine.jobs.wait(request.jobId);
  const result = await engine.recall({ query: '项目使用什么数据库？' });
  console.log(result.context);
} finally {
  // 关闭调度器和存储线程，确保持久化操作结束。
  await engine.close();
}
```

SDK 提供 `memories`、`remember`、`recall`、`workspaces`、`jobs`、`namespaces`、`users`、`conflicts`、`feedback`、`maintenance` 和 `admin`。直接 SDK 是可信宿主接口；不可信用户通过 HTTP 登录会话访问，不应允许客户端指定 `forContext`。

## 模型与离线运行

默认启用 SQLite FTS5、中文二元词/字和英文词索引、时间过滤及本地规则编码；未配置 Embedding 时响应明确标记 `vector` 渠道不可用。

`createMemoryEngine({ embedding: { id, embed } })` 可注入本地模型；向量保存为 SQLite Float32 BLOB，按模型空间及正文版本隔离。没有下载模型时不会自动联网。

`loadLocalEmbedding({ modelId, modelDir })` 支持带 `memory-model.json` 清单的 Transformers 本地模型目录。先使用 `createModelManifest()` 记录资源版本、维度及文件哈希，再单独安装推理依赖。加载前校验全部文件，推理在独立线程内进行并关闭远程下载；向量空间包含资源指纹。使用结束后调用 `dispose()`。完整准备、真实 tokenizer 与关闭示例见 [本地模型说明](./docs/local-models.md)。真实模型包的资源及质量验证仍需完成，自动语义抽取目前采用规则及调用方结构化事实。

## 检查

```sh
npm run check
```

包括 ESLint、Prettier、文件大小检查及 Node.js 集成测试。CI 配置覆盖 Windows/Linux 的 Node.js 22/24；本地已验证环境以实际检查输出为准。

`npm test` 将测试文件并发限制为 4，避免各文件内部的存储与模型线程叠加成过多并发。需要评测更高并发时单独建立容量测试，不通过无限增加基础测试进程数量代替压测。

浏览器集成测试使用 `npm run test:browser`，需先 `npx playwright install chromium`。Windows 已安装 Edge 时可以设置 `PLAYWRIGHT_BROWSER_CHANNEL=msedge` 后运行，浏览器测试使用独立临时数据库。

## 备份与密码重置

管理后台备份采用异步任务，可通过 `engine.lifecycle.backup({idempotencyKey})` 提交并使用 `jobs.wait(jobId)` 等待；`POST /admin/backups` 返回 202，不直接返回文件名。完整发布、重试和故障恢复规则见 [备份说明](./docs/backups.md)。

`engine.maintenance.backup()` 通过 SQLite `VACUUM INTO` 创建一致性副本，`inspect(name)` 检查备份。文件在 `data/backups/`，默认清理会话。OWNER 可在后台预检并确认异步恢复，服务自行进入维护模式，完成后重新登录；SDK 使用 `maintenance.restore({name,previewToken,confirm:true,reason})`。使用离线命令时，恢复前停止应用：

```sh
node scripts/restore.js ./data <备份文件名.sqlite>
```

恢复命令检查备份完整性并重放本地删除记录。不要把运行中的数据库只复制主文件作为备份；数据目录不能作为多机共享 SQLite 文件使用。

数据库和来源原文先在临时目录准备，校验后共同安装。安装失败回滚到原实例；进程中断后，下次启动或离线维护会在目录锁内处理恢复日志，再开放数据库。成功恢复保留成对的 `pre-restore-<标识>.sqlite` 与 `pre-restore-<标识>.sources/` 恢复点，按数据目录权限保护。OWNER 可在“存储与备份”预览并确认过期资源清理，或显式启用每日保留周期任务；默认自动清理关闭，详见 [保留周期说明](./docs/retention.md)。

引擎、恢复和密码重置会独占数据目录，已被占用时拒绝执行并返回 `DATA_DIRECTORY_BUSY`。多个 Agent 使用同一 SDK 实例或本地 HTTP 共享记忆；正常关闭和进程崩溃后锁自动释放。`.owner.sqlite` 是运行锁文件，运行期间保持该文件不变。重启会立即接管旧实例未完成的任务，保留幂等语义。

忘记密码时停止应用，设置环境变量 `MEMORY_RESET_PASSWORD` 后运行 `node scripts/reset-password.js`；该操作要求数据目录权限并撤销旧会话，不提供匿名密码重置 API。

## 交付范围

实现与剩余需求逐项记录在 [开发进度](./docs/implementation.md)。需求和架构文件仍包含后续阶段规划；未完成项不能仅凭现有测试通过视为已交付。

- [需求文档](./docs/pro.md)
- [SDK 与 HTTP 契约](./docs/api.md)
- [架构设计](./docs/architecture.md)
- [管理后台需求](./docs/admin.md)
- [开发规范](./AGENTS.md)