hola-mind

轻量级、高性能的 AI Agent 大脑/记忆系统，基于 Bun 构建。

零依赖 — 仅使用 Bun 原生 API（bun:sqlite、Bun fs）。

English | 中文

为什么选择 hola-mind？

| 特性 | hola-mind | IronClaw | ZeroClaw Memory | OpenViking | |---|---|---|---|---| | 语言 | TypeScript (Bun) | Rust | Rust | TypeScript | | 存储 | SQLite + 文件系统 | PostgreSQL + pgvector + Markdown 文件 | SQLite | SQLite + 文件系统 | | 全文搜索 | FTS5 + CJK LIKE 降级 | BM25 (PostgreSQL) | FTS5 (BM25) | FTS5 | | 向量搜索 | 余弦相似度 (BLOB) | pgvector | 余弦相似度 (BLOB) | 余弦相似度 | | 混合搜索 | ✅ RRF 融合 (k=60) | ✅ BM25 + Vector + RRF | ✅ 加权线性融合 | ❌ 结果分离 | | 记忆生命周期 | write / read / forget / delete | write / read（文件系统） | store / recall / forget | write / read / delete | | 软删除 | ✅ forgotten_at 时间戳 | ❌ | ✅ 软删除标志 | ❌ 仅硬删除 | | 记忆衰减 | ✅ 指数衰减 + 访问提升 + 自动淘汰 | ❌ 无衰减 | ⚠️ 基础 TTL 衰减 | ❌ 无衰减 | | RAG 召回 | ✅ search({ includeContent }) | ✅ Markdown 文件始终可读 | ✅ recall() 返回内容 | ❌ 需额外 read 调用 | | 重要性评分 | ✅ 每节点 0.0–1.0 | ❌ | ❌ | ❌ | | 访问追踪 | ✅ accessed_at + 提升 | ❌ | ❌ | ❌ | | 固定上下文 | ✅ pinned + getPinned() | ✅ AGENTS.md 始终加载 | ❌ | ❌ | | 多工作空间 | ✅ 工作空间 + 项目 + 全局 | ❌ 单工作空间 | ⚠️ 单级沙箱 | ✅ 多实例 | | 项目隔离 | ✅ 虚拟 project: 标签 | ❌ | ❌ | ❌ | | 知识回退 | ✅ 三步（ws → project → global） | ❌ | ❌ | ❌ | | 技能打包 | ✅ .skill 导入/导出 + manifest.json | ❌ | ❌ | ❌ | | CJK 支持 | ✅ LIKE 降级处理 CJK 文本 | ❌ | ❌ 已知问题 | ❌ | | 标签过滤 | ✅ 搜索 + 列表 | ❌ | ❌ | ❌ | | 加密 | ❌（基础设施层） | ✅ AES256GCM 静态加密 | ❌ | ❌ | | 后端插件 | ❌ 仅 SQLite | ❌ 仅 PostgreSQL | ✅ sqlite / postgres / markdown | ❌ 仅 SQLite | | HTTP API | ✅ 内置 REST 服务 | ❌ 仅 CLI | ❌ 仅库模式 | ✅ REST + WebSocket | | 依赖 | 零（Bun 原生） | PostgreSQL + pgvector | 零（Rust 原生） | 多个 npm 包 | | 二进制大小 | N/A（Bun 运行时） | Rust 二进制 | 3.4MB 独立运行 | N/A（Node 运行时） |

特性

• 三层组织 — memories（短期记忆，支持 TTL 过期）、knowledge（永久知识库）、skills（可复用技能）
• 项目支持 — 通过 project: tag 约定实现虚拟项目命名空间
• 混合搜索 — FTS5 + 向量相似度搜索，RRF（Reciprocal Rank Fusion） 分数融合
• 记忆衰减 — 自动重要性衰减 + 访问提升 + 自动淘汰，实现自维护记忆
• 软删除 — forget() 带 forgotten_at 时间戳，支持可审计的记忆生命周期
• RAG 优化召回 — search({ includeContent: true }) 一次调用返回完整内容
• 多工作空间 — 工作空间间数据隔离，全局共享技能和知识
• 三步知识回退 — 工作空间 → 项目 → 全局，自动解析
• 技能注册 — 注册/导出技能，支持 manifest.json 元数据打包
• HTTP API — 内置 REST 服务（Bun.serve()）
• mind:// URI — 使用 mind:// 协议寻址数据

安装

# Bun（推荐）
bun add hola-mind

# npm
npm install hola-mind

注意： hola-mind 使用 Bun 原生 API（bun:sqlite、Bun fs），请确保你的项目使用 Bun 运行。

快速开始

import { Mind } from 'hola-mind'

const mind = new Mind('./data')

// 写入
await mind.write('memories/chat/会议记录', {
  summary: 'Sprint 计划讨论',
  content: '完整的会议记录...',
  tags: ['会议', 'sprint'],
  ttl: 86400 // 24 小时后过期
})

// 读取
const result = await mind.read('memories/chat/会议记录')

// 搜索（RRF 混合融合：FTS5 + 向量）
const results = await mind.search('sprint 计划', { scope: 'memories' })

// RAG 召回 — 搜索 + 一次获取完整内容
const withContent = await mind.search('sprint 计划', { includeContent: true })

// 软删除记忆（仍可审计）
await mind.forget('memories/chat/会议记录')

// 清理过期 + 衰减自动遗忘 + 关闭
const { removed, forgotten } = await mind.cleanup()
await mind.close()

API 参考

📖 完整 API 文档请查看 api.md（English & 中文）。

真实使用场景

场景一：单 Agent — 个人编程助手

一个能记住你偏好、积累项目知识、学习可复用技能的编程助手。

import { Mind } from 'hola-mind'

const mind = new Mind({
  workspace: './agent-data',
  embed: myEmbedFn,
  autoCleanup: { enabled: true, interval: 3600 }
})

// Agent 从对话中学习用户偏好
await mind.write('memories/preferences/coding-style', {
  summary: '用户偏好 TypeScript strict 模式，函数式风格',
  content: '始终使用 strict: true。偏好 map/filter 而非 for 循环...',
  tags: ['偏好', 'typescript'],
  ttl: 604800 // 每周刷新
})

// Agent 积累项目知识
await mind.write('knowledge/project/architecture', {
  summary: 'Monorepo，3 个包：core、web、cli',
  content: '完整的架构文档...',
  tags: ['架构', 'monorepo']
})

// Agent 注册学到的技能
await mind.registerSkill('coding/test-pattern', {
  path: './learned-skills/test-pattern',
  summary: '使用 AAA 模式编写 vitest 单元测试',
  tags: ['测试', 'vitest']
})

// 对话时，Agent 搜索相关上下文
const memories = await mind.search('typescript 配置', { scope: 'memories' })
const knowledge = await mind.search('项目结构', { scope: 'knowledge' })
const skills = await mind.search('如何写测试', { scope: 'skills' })

// 组装 LLM prompt 上下文
const context = [...memories, ...knowledge, ...skills]
  .map(r => `[${r.scope}] ${r.summary}`)
  .join('\n')

场景二：多 Agent — 专业化 Agent 团队

多个 Agent 共享全局技能和知识，但各自维护独立的对话记忆。

// 共享知识库 + 技能注册中心
const globalDir = './data/global'

// DevOps Agent — 负责部署和基础设施
const devops = new Mind({
  global: globalDir,
  workspace: './data/ws/devops',
  permissions: { canWriteGlobal: true }  // 管理员：可注册全局技能
})

// Coding Agent — 负责代码生成和审查
const coder = new Mind({
  global: globalDir,
  workspace: './data/ws/coder',
  permissions: { canWriteGlobal: false }  // 只能读取全局
})

// QA Agent — 负责测试
const qa = new Mind({
  global: globalDir,
  workspace: './data/ws/qa',
  permissions: { canWriteGlobal: false }
})

// DevOps 注册部署技能 → 所有 Agent 可用
await devops.registerSkill('devops/docker-deploy', {
  path: './skills/docker-deploy',
  summary: '使用 Docker Compose 部署应用'
})

// Coder 被问到"如何部署"时搜索技能
const skills = await coder.search('部署应用')
// → 找到 DevOps 注册的 docker-deploy 技能 ✅

// 每个 Agent 的记忆是隔离的
await coder.write('memories/chat/code-review-01', {
  summary: '审查 auth 模块，发现 XSS 漏洞',
  content: '详细审查笔记...'
})

await qa.read('memories/chat/code-review-01')  // → null（隔离）
await qa.search('XSS 漏洞', { scope: 'memories' })  // → 空（隔离）

// 共享全局知识对所有 Agent 可见
await devops.write('knowledge/infra/k8s-config', {
  summary: '生产环境 Kubernetes 配置',
  content: 'apiVersion: apps/v1...',
  scope: 'global'
})

await coder.read('knowledge/infra/k8s-config')  // ✅ 回退到全局
await qa.search('kubernetes', { scope: 'knowledge' })  // ✅ 包含全局结果

场景三：多项目 — 管理多个客户项目的 AI 团队

AI 团队跨多个客户项目工作，共享技能但隔离项目知识。

// 所有项目共享技能
const globalDir = './data/global'

// Alice 在电商项目
const aliceEcom = new Mind({
  global: globalDir,
  workspace: './data/ws/alice',
  project: 'ecommerce'
})

// Alice 切换到 CRM 项目（同一工作空间，不同项目）
const aliceCRM = new Mind({
  global: globalDir,
  workspace: './data/ws/alice',
  project: 'crm'
})

// Bob 也在电商项目
const bobEcom = new Mind({
  global: globalDir,
  workspace: './data/ws/bob',
  project: 'ecommerce'
})

// 写入项目专属知识（在全局 DB 中打 tag）
await aliceEcom.write('knowledge/apis/payment', {
  summary: 'Stripe 支付集成规范',
  content: 'POST /api/pay { amount, currency }...',
  scope: 'project'  // 自动打上 'project:ecommerce' tag
})

await aliceCRM.write('knowledge/apis/contacts', {
  summary: 'CRM 联系人 API 文档',
  content: 'GET /api/contacts?page=1...',
  scope: 'project'  // 自动打上 'project:crm' tag
})

// Bob 能看到电商项目知识（相同 project tag）
await bobEcom.read('knowledge/apis/payment')  // ✅ scope: 'project'

// Alice 在 CRM 中看不到电商项目知识
await aliceCRM.read('knowledge/apis/payment')
// → scope: 'global'（穿透项目过滤，回退到全局）

// 写入纯全局知识（无项目 tag，所有人可见）
await aliceEcom.write('knowledge/company/handbook', {
  summary: '公司工程手册',
  content: '编码规范、代码审查流程...',
  scope: 'global'
})

// 项目内搜索
const ecomResults = await aliceEcom.search('支付 API', { scope: 'knowledge' })
// → 包含：工作空间 + 电商标签 + 纯全局知识

const crmResults = await aliceCRM.search('API', { scope: 'knowledge' })
// → 包含：工作空间 + CRM 标签 + 纯全局知识
// → 不包含电商标签的知识

// 工作空间记忆属于 alice，不论项目
await aliceEcom.write('memories/chat/payment-debug', {
  summary: '调试 Stripe webhook 超时问题',
  content: 'Webhook 失败是因为...',
  ttl: 604800
})

// 同一工作空间 → alice 在 CRM 也能看到自己的记忆
await aliceCRM.read('memories/chat/payment-debug')  // ✅（同一工作空间）

案例研究：用 hola-mind 实现 OpenClaw 的记忆系统

OpenClaw 是一个使用扁平文件、基于 Markdown 的记忆系统的 AI Agent，包含每日日志和长期知识文件。以下是如何用 hola-mind 实现 OpenClaw 的记忆架构：

OpenClaw 记忆模型 → hola-mind 映射

| OpenClaw 概念 | hola-mind 对应 | 说明 | |---|---|---| | 每日日志 (memory/YYYY-MM-DD.md) | memories/logs/YYYY-MM-DD | 短期记忆，TTL 自动过期 | | MEMORY.md（用户偏好、决策） | knowledge/agent/memory | 永久长期知识 | | USER.md（用户身份） | knowledge/agent/user | 用户画像 | | IDENTITY.md（Agent 人设） | knowledge/agent/identity | Agent 自我定义 | | SOUL.md（行为规则） | knowledge/agent/soul | Agent 约束和准则 | | TOOLS.md（工具清单） | skills/tools/inventory | 可复用工具描述 | | JSONL 对话记录 | memories/transcripts/session-* | 审计日志，带 TTL |

实现代码

import { Mind } from 'hola-mind'

// 初始化混合搜索（FTS5 + 向量）
const claw = new Mind({
  workspace: './openclaw-data',
  embed: myEmbedFn,
  autoCleanup: { enabled: true, interval: 86400 }  // 每日清理
})

// ──────────────────────────────────────────────
// 1. 每日日志 → memories（带 TTL）
// ──────────────────────────────────────────────
const today = new Date().toISOString().split('T')[0]  // '2026-02-18'

// 追加风格：每次交互成为一条记忆条目
await claw.write(`memories/logs/${today}/interaction-001`, {
  summary: '用户询问 Docker 部署方案',
  content: `[14:30] 用户: 应该怎么部署？\n[14:30] Agent: 基于你的技术栈，我推荐...`,
  tags: ['对话', 'docker', '部署'],
  ttl: 604800  // 保留 7 天后自动清理
})

await claw.write(`memories/logs/${today}/interaction-002`, {
  summary: '用户确认选择 Docker Compose 而非 K8s',
  content: `[14:35] 用户: 用 Docker Compose 吧\n[14:35] Agent: 适合你的规模...`,
  tags: ['对话', '决策', 'docker-compose'],
  ttl: 604800
})

// ──────────────────────────────────────────────
// 2. 长期记忆文件 → knowledge（永久）
// ──────────────────────────────────────────────

// MEMORY.md 对应：经过整理的持久化知识
await claw.write('knowledge/agent/memory', {
  summary: '用户偏好 Docker Compose，使用 TypeScript，部署到 AWS',
  content: `# 长期记忆\n\n## 用户偏好\n- Docker Compose 优于 K8s\n- TypeScript strict 模式\n- AWS 托管\n\n## 关键决策\n- 2026-02-18: 选择 Docker Compose 部署`,
  tags: ['长期记忆', '偏好', '决策']
})

// USER.md 对应
await claw.write('knowledge/agent/user', {
  summary: '高级全栈开发者，专注 SaaS 产品',
  content: `# 用户画像\n角色: 高级全栈开发者\n技术栈: TypeScript, React, Node.js, PostgreSQL`,
  tags: ['用户画像']
})

// IDENTITY.md + SOUL.md 对应
await claw.write('knowledge/agent/identity', {
  summary: '专注于整洁代码和最佳实践的编程助手',
  content: `# Agent 身份\n我是一个优先考虑整洁、可维护代码的编程助手...`,
  tags: ['身份', '人设']
})

// ──────────────────────────────────────────────
// 3. 工具 → skills
// ──────────────────────────────────────────────
await claw.registerSkill('tools/file-operations', {
  path: './skills/file-ops',
  summary: '读写和操作工作区文件',
  tags: ['工具', '文件系统']
})

await claw.registerSkill('tools/git-operations', {
  path: './skills/git-ops',
  summary: 'Git commit、push、branch 和 PR 管理',
  tags: ['工具', 'git']
})

// ──────────────────────────────────────────────
// 4. 混合检索（与 OpenClaw 一致）
// ──────────────────────────────────────────────

// 用户提新问题时，Agent 检索相关上下文：
async function getContext(query: string) {
  // 近期对话日志
  const recentMemories = await claw.search(query, {
    scope: 'memories', limit: 5, method: 'auto'
  })

  // 永久知识（用户画像、偏好、历史决策）
  const knowledge = await claw.search(query, {
    scope: 'knowledge', limit: 3, method: 'auto'
  })

  // 可用工具/技能
  const skills = await claw.search(query, {
    scope: 'skills', limit: 3, method: 'auto'
  })

  return { recentMemories, knowledge, skills }
}

// 用户问: "帮我部署"
const ctx = await getContext('部署应用')
// recentMemories → "用户确认使用 Docker Compose"（来自今天日志）
// knowledge      → "用户偏好 Docker Compose，部署到 AWS"
// skills         → "Git 操作"（用于推送）、"文件操作"（用于配置）

// ──────────────────────────────────────────────
// 5. 记忆生命周期（自动管理）
// ──────────────────────────────────────────────

// 旧的每日日志通过 TTL + autoCleanup 自动过期
// 长期知识持久存在，直到手动更新
// 技能永久保留

// 优雅退出
await claw.close()

相比 OpenClaw 扁平文件方案的优势

| 方面 | OpenClaw（原始文件） | hola-mind | |---|---|---| | 搜索 | 手动 grep / 外部索引 | 内置 FTS5 + 向量搜索 | | TTL 清理 | 手动删除 | TTL + autoCleanup 自动管理 | | 多 Agent | 手动目录管理 | 原生隔离 + 全局共享 | | 项目隔离 | 手动目录管理 | 虚拟项目命名空间 | | 元数据 | YAML frontmatter 解析 | 结构化 SQLite 元数据 | | API 访问 | 仅文件 I/O | SDK + HTTP REST API |

数据组织

data/
├── global/                     # 共享技能 + 知识
│   ├── skills/
│   ├── knowledge/
│   └── mind.db
└── workspaces/
    └── agent/
        ├── memories/           # 短期记忆（TTL）
        ├── knowledge/          # 工作空间私有知识
        └── mind.db

知识回退优先级： 工作空间 → 项目（tag 过滤） → 全局。 嵌入策略： 仅 summary 用于向量嵌入；content 通过 FTS5 全文搜索。

开发

bun install
bun test
bun build src/index.ts --target bun --outdir dist

许可证

MIT © hery-node