@aigclab/memory

Standalone memory system extracted from OpenClaw: index Markdown files under a root directory and run semantic + keyword search.

Install

npm install @aigclab/memory

Usage (library)

import { createMemory } from "@aigclab/memory";

const memory = await createMemory({
  memoryRoot: "./memory",       // directory containing MEMORY.md and memory/*.md
  storePath: "./.cache/memory.sqlite",
  embedding: {
    provider: "openai",
    apiKey: process.env.OPENAI_API_KEY,
    model: "text-embedding-3-small",
  },
});

// Search
const results = await memory.search("user preferences");
// Read a file
const { text, path } = await memory.readFile({ relPath: "memory/2025-01-15.md", from: 1, lines: 50 });
// Sync index (or leave to watch + interval)
await memory.sync({ force: true });
// Status
const status = memory.status();
await memory.close();

Configuration

• memoryRoot (required): Root directory for MEMORY.md and memory/*.md.
• storePath (required): SQLite database path for the index.
• embedding: provider: "openai" | "none", and when openai: apiKey, optional baseUrl, model.
• chunking: tokens (default 400), overlap (default 80).
• sync: watch, watchDebounceMs, intervalMinutes.
• query: maxResults, minScore, hybrid (vectorWeight, textWeight, mmr, temporalDecay).
• cache: enabled, maxEntries.
• extraPaths: Extra paths (relative to memoryRoot or absolute) to index as .md.
• vector: enabled, optional extensionPath for sqlite-vec.

MCP integration (optional)

本包是 库，不提供现成的 MCP 服务进程。若要在 Cursor 等支持 MCP 的客户端里用「记忆」能力，需要有一个 调用了本库 的 MCP 服务（你自己写的脚本、或其它项目提供的 MCP 服务）。

在你自己实现的 MCP 服务里，用 getMemoryManager 和 handleMemoryTool 把记忆能力接到 MCP 的 tool 上：

import { getMemoryManager, handleMemoryTool } from "@aigclab/memory";

const options = {
  config: { memoryRoot: "./memory", storePath: "./.cache/memory.sqlite" },
  toolNames: { search: "memory_search", get: "memory_get" },
  // 可选：后台 Flush + 抽取。首次调用任一 memory 工具时自动启动，每次调用续命 1 小时，闲置 1 小时后停止。设 background: { enable: false } 可关闭。
  background: { transcriptDir: "%LOCALAPPDATA%/memory", idleShutdownHours: 1 },
};
// 在你的 MCP tool 处理函数里：
const result = await handleMemoryTool(toolName, args, options);

后台行为：当 background.enable !== false 时，第一次调用任意 memory 工具会启动「Flush 触发 + 对话抽取」循环；之后每次工具调用都会将「闲置 1 小时自动停止」的计时重置；若 1 小时内没有新的工具调用，后台自动停止，下次调用时再启动。

若本包日后提供可执行入口（例如通过 npx @aigclab/memory mcp 启动 MCP 服务），则 Cursor 的 MCP 配置会类似：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@aigclab/memory", "mcp", "--memoryRoot", "D:\\your-project\\memory", "--storePath", "D:\\your-project\\.cache\\memory.sqlite"],
      "env": { "OPENAI_API_KEY": "your_openai_api_key" }
    }
  }
}

本地调试

{
  "memory": {
      "command": "node",
      "args": [
        "D:\\memory\\dist\\cli.js",
        "mcp",
        "--memoryRoot",
        "D:\\memory",
        "--storePath",
        "D:\\memory\\.cache\\memory.sqlite"
      ]
  }
}

当前版本没有上述 mcp 子命令，如需在 Cursor 中使用，需自行实现一个 MCP 服务进程并在其中调用本库的 handleMemoryTool。

职责划分

| 模块 | 职责 | | ---------------------------- | -------------------------------------------------------------------------------- | | config.ts | 配置类型、默认值、路径解析（memoryRoot / storePath / extraPaths） | | src/logger.ts | 日志接口与默认/静默实现 | | src/utils.ts | truncateUtf16Safe 等工具 | | src/fs-utils.ts | 文件存在检查、statRegularFile | | src/types.ts | 对外类型：MemorySearchResult、MemoryProviderStatus、MemorySearchManager 等 | | src/internal.ts | 内部：列举 MD、构建 file entry、分块、哈希、路径规范化 | | src/memory-schema.ts | SQLite 表结构（meta, files, chunks, embedding_cache, FTS5） | | src/sqlite.ts | 加载 node:sqlite | | src/sqlite-vec.ts | 可选加载 sqlite-vec 扩展 | | src/embedding-*.ts | 嵌入输入/模型/分块限制 | | src/http.ts | 简单 POST JSON（用于 OpenAI 等） | | src/embeddings-openai.ts | OpenAI 嵌入（apiKey/baseUrl/model） | | src/embeddings.ts | 根据配置创建嵌入提供方（当前仅 openai / none） | | src/manager-search.ts | 向量检索、关键词检索（FTS）、listChunks | | src/query-expansion.ts | 关键词抽取（FTS 用） | | src/hybrid.ts | 混合结果合并、FTS 查询构建、BM25→分数 | | src/mmr.ts | MMR 重排 | | src/temporal-decay.ts | 时间衰减 | | src/manager.ts | 索引管理：建库、watch、定时同步、indexFile、search、readFile、status、close | | src/create-memory.ts | createMemory(options)，返回 MemorySearchManager | | src/mcp-server.ts | MCP 用：getMemoryManager、handleMemoryTool（memory_search / memory_get） | | src/index.ts | 汇总导出（含 MCP 入口） |

内容整理命令

「整理当前项目」「整理记忆」「梳理项目」「项目复盘」