[English](./README.en.md) | 中文

# @easbot/note

> Note Knowledge Base - 非结构化记忆和文档知识库管理系统

## 简介

Note Knowledge Base 是一个基于 TypeScript/Node.js 的非结构化记忆和文档知识库管理系统，支持混合搜索（向量相似度 + 全文搜索 + 图关系推理）和 LLM 驱动的知识摄取。

## 特性

- **文档摄取**：支持 Markdown、纯文本解析，智能分块和嵌入生成
- **混合搜索**：向量相似度 + FTS5 全文搜索 + 图关系推理，可配置权重
- **图查询**：SQL 接口查询节点和边，支持路径查找
- **实体管理**：节点和边的完整 CRUD 操作
- **模型注入**：支持 AI SDK 规范的 LLM 和 Embedding 模型
- **状态监控**：提供知识库状态和健康检查
- **智能分块**：使用 Markdown 智能分块，保护代码块和内联代码

## 安装

```bash
pnpm add @easbot/note
```

## 快速开始

### 基本使用

```typescript
import { NoteKnowledge } from '@easbot/note';

const kb = new NoteKnowledge({
  storagePath: './data/knowledge.db',
  vectorDims: 768,
  chunkSize: 1000,
  chunkOverlap: 200,
  embedding: yourEmbeddingModel,
  llm: yourLLM,
  hybridSearch: {
    vectorWeight: 0.7,
    ftsWeight: 0.3,
    graphWeight: 0.0,
    rerankTopK: 10,
  },
});

await kb.initialize();

const result = await kb.ingestDocument('./docs/example.md');
console.log(`创建了 ${result.chunksCreated} 个块`);

const results = await kb.search('查询内容', { limit: 10 });
for (const r of results) {
  console.log(`[${r.score}] ${r.content}`);
}

await kb.close();
```

### 图查询

```typescript
const node1 = await kb.createNode('实体A', '类型1', { prop: 'value' });
const node2 = await kb.createNode('实体B', '类型1');

const edge = await kb.createEdge(node1.id, node2.id, 'RELATED_TO');

const paths = await kb.findPath('实体A', '实体B', 3);

const nodes = await kb.queryNodes('SELECT * FROM nodes WHERE type = ?', ['类型1']);
```

## 开发

```bash
# 安装依赖
pnpm install

# 构建
pnpm build

# 测试
pnpm test

# 类型检查
pnpm type-check
```

## 许可证

MIT
