# hmemory

**Repository Path**: duzc2/hmemory

## Basic Information

- **Project Name**: hmemory
- **Description**: HMemory 是一个高性能语义记忆库，追求 SQLite 级别的代码质量、可靠性与稳定性。基于 Bun 运行时和 LanceDB 向量数据库构建，提供类人记忆能力，包括语义搜索、时间衰减加权和自动 LRU 遗忘。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-02-11
- **Last Updated**: 2026-02-17

## Categories & Tags

**Categories**: ai

**Tags**: None

## README

# HMemory 🧠

<div align="center">

[![Tests](https://img.shields.io/badge/tests-212%20passing-brightgreen)](tests)
[![Coverage](https://img.shields.io/badge/coverage-%3E90%25-brightgreen)](TESTING.md)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Bun](https://img.shields.io/badge/runtime-Bun-orange.svg)](https://bun.sh)
[![TypeScript](https://img.shields.io/badge/lang-TypeScript-blue.svg)](https://typescriptlang.org)

**[English](#english) | [中文](#中文)**

</div>

---

<a name="english"></a>
## English

### AgentMemory - AI Agent 对话记忆系统

AgentMemory 为 AI Agent 提供**对话记忆的自动提炼、持久化存储和语义检索**能力。基于 HMemory 构建，支持实体追踪、代词消解和对话摘要维护。

### HMemory - 底层向量存储

HMemory 是一个**高性能语义记忆库**，追求 SQLite 级别的代码质量、可靠性与稳定性。基于 Bun 运行时和 LanceDB 向量数据库构建，提供类人记忆能力，包括语义搜索、时间衰减加权和自动 LRU 遗忘。

### ✨ Features

| Feature | Description | Status |
|---------|-------------|--------|
| 🎯 **Semantic Search** | Vector similarity search with time-decay weighted scoring | ✅ |
| ⚡ **High Performance** | < 50ms search latency on 10K records | ✅ |
| 🧠 **Human-like Forgetting** | Automatic LRU eviction based on `last_recalled` | ✅ |
| ⏱️ **Time-Aware** | Exponential decay simulates human memory curve | ✅ |
| 🔄 **Async Queue** | Read-priority queue for optimal responsiveness | ✅ |
| 📦 **TypeScript** | Complete type safety with strict checks | ✅ |
| 💾 **Persistent** | Local LanceDB storage with automatic indexing | ✅ |

### 🚀 Quick Start - AgentMemory

```bash
# Install from npm
bun add hmemory
# or
npm install hmemory

# Or install directly from Git
bun add git+https://github.com/yourusername/hmemory.git
# or
npm install git+https://github.com/yourusername/hmemory.git
```

```typescript
import { AgentMemory } from 'hmemory';

// Create AgentMemory instance
const memory = await AgentMemory.create({
  dbPath: './data/memory.db',
  fileStoragePath: './data/files',
  llm: {
    baseUrl: 'https://api.example.com/v1',
    apiKey: 'your-api-key',
    model: 'gpt-4o-mini',
  },
  embedding: {
    baseUrl: 'https://api.example.com/v1',
    apiKey: 'your-api-key',
    model: 'text-embedding-3-small',
    dimensions: 1536,
  },
});

// Process conversation (batch recommended)
await memory.processConversation([
  { role: 'user', name: '张三', content: '你好，我是张三，喜欢编程' },
  { role: 'assistant', name: 'AI', content: '你好张三！很高兴认识你' },
  { role: 'user', name: '张三', content: '我最喜欢读科幻小说' },
]);

// Semantic search
const results = await memory.recall({
  query: '张三喜欢什么',
  limit: 5,
  minConfidence: 0.5,
});

// Close
await memory.close();
```

### 📊 Performance Benchmarks

| Operation | Target | Actual | Data Scale |
|-----------|--------|--------|------------|
| Single Add | < 10ms | ~5ms | - |
| Batch Add (1000) | < 50ms/record | ~30ms/record | 1K records |
| Vector Search | < 50ms | ~25ms | 10K records |
| Count | < 10ms | ~2ms | Any |
| Clear (100K) | < 1s | ~500ms | 100K records |

*Benchmarks run on AMD Ryzen 5 5600X, 32GB RAM, NVMe SSD*

### 📚 Documentation

| Document | Description |
|----------|-------------|
| [📖 Usage Guide](docs/USAGE.md) | Complete API reference for users |
| [🏗️ Contributor Guide](docs/CONTRIBUTOR.md) | Architecture and development guide |
| [🚀 Quick Start](docs/QUICK_START.md) | Get started in 5 minutes |
| [📋 API Reference](docs/API_REFERENCE.md) | Low-level HMemory API documentation |
| [🎓 Tutorials](docs/TUTORIALS/) | Step-by-step guides |
| [🧪 Testing](TESTING.md) | Test strategy and coverage |
| [🔒 Security](docs/SECURITY.md) | Security considerations |
| [❓ FAQ](docs/FAQ.md) | Frequently asked questions |
| [📝 Changelog](CHANGELOG.md) | Version history |

### 🏛️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│                   (HMemory Public API)                      │
├─────────────────────────────────────────────────────────────┤
│                     Queue Engine                            │
│           (Read-Priority Async Scheduling)                  │
├─────────────────────────────────────────────────────────────┤
│                   Search Scorer                             │
│        (Similarity × Time Decay Scoring)                    │
├─────────────────────────────────────────────────────────────┤
│                   Storage Engine                            │
│              (LanceDB + Scalar Indexing)                    │
├─────────────────────────────────────────────────────────────┤
│                 Tiered Eviction Policy                      │
│       (Precise < 10K records / Threshold >= 10K)            │
└─────────────────────────────────────────────────────────────┘
```

### 🎯 Use Cases

- **RAG Systems** - Retrieval-Augmented Generation for LLMs
- **Knowledge Bases** - Semantic document search
- **AI Agent Memory** - Persistent conversation context
- **Code Intelligence** - Semantic code search
- **Note Management** - Smart note retrieval

### 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.

---

<a name="中文"></a>
## 中文

### 类人记忆系统

HMemory 是一个为 AI Agent 设计的**高性能语义记忆库**，追求 SQLite 级别的代码质量、可靠性与稳定性。基于 Bun 运行时和 LanceDB 向量数据库构建，提供类人记忆能力，包括语义搜索、时间衰减加权和自动 LRU 遗忘。

### ✨ 特性

| 特性 | 描述 | 状态 |
|------|------|------|
| 🎯 **语义搜索** | 基于向量相似度的搜索，支持时间衰减加权评分 | ✅ |
| ⚡ **高性能** | 10K 记录搜索延迟 < 50ms | ✅ |
| 🧠 **类人遗忘** | 基于 `last_recalled` 的自动 LRU 驱逐 | ✅ |
| ⏱️ **时间感知** | 指数衰减模拟人类记忆曲线 | ✅ |
| 🔄 **异步队列** | 读优先队列，优化响应性 | ✅ |
| 📦 **TypeScript** | 完整类型安全，严格检查 | ✅ |
| 💾 **持久化** | 本地 LanceDB 存储，自动索引 | ✅ |

### 🚀 快速开始 - AgentMemory

```bash
# 安装
bun add hmemory
# 或
npm install hmemory
```

```typescript
import { AgentMemory } from 'hmemory';

// 创建 AgentMemory 实例
const memory = await AgentMemory.create({
  dbPath: './data/memory.db',
  fileStoragePath: './data/files',
  llm: {
    baseUrl: 'https://api.example.com/v1',
    apiKey: 'your-api-key',
    model: 'gpt-4o-mini',
  },
  embedding: {
    baseUrl: 'https://api.example.com/v1',
    apiKey: 'your-api-key',
    model: 'text-embedding-3-small',
    dimensions: 1536,
  },
});

// 处理对话（推荐批量）
await memory.processConversation([
  { role: 'user', name: '张三', content: '你好，我是张三，喜欢编程' },
  { role: 'assistant', name: 'AI', content: '你好张三！很高兴认识你' },
  { role: 'user', name: '张三', content: '我最喜欢读科幻小说' },
]);

// 语义搜索
const results = await memory.recall({
  query: '张三喜欢什么',
  limit: 5,
  minConfidence: 0.5,
});

// 关闭
await memory.close();
```

### 📊 性能基准

| 操作 | 目标 | 实际 | 数据规模 |
|------|------|------|----------|
| 单条添加 | < 10ms | ~5ms | - |
| 批量添加 (1000) | < 50ms/条 | ~30ms/条 | 1K 条 |
| 向量搜索 | < 50ms | ~25ms | 10K 条 |
| 计数 | < 10ms | ~2ms | 任意 |
| 清空 (100K) | < 1s | ~500ms | 100K 条 |

*基准测试环境：AMD Ryzen 5 5600X, 32GB RAM, NVMe SSD*

### 📚 文档

| 文档 | 描述 |
|------|------|
| [📖 使用文档](docs/USAGE.md) | 面向用户的完整 API 参考 |
| [🏗️ 开发文档](docs/CONTRIBUTOR.md) | 面向开发者的架构设计指南 |
| [🚀 快速入门](docs/QUICK_START.md) | 5 分钟快速上手 |
| [📋 API 参考](docs/API_REFERENCE.md) | 底层 HMemory API 文档 |
| [🎓 教程](docs/TUTORIALS/) | 手把手教程 |
| [🧪 测试说明](TESTING.md) | 测试策略与覆盖率 |
| [🔒 安全说明](docs/SECURITY.md) | 安全注意事项 |
| [❓ 常见问题](docs/FAQ.md) | 常见问题解答 |
| [📝 变更日志](CHANGELOG.md) | 版本历史 |

### 🏛️ 架构

```
┌─────────────────────────────────────────────────────────────┐
│                      应用层                                 │
│                   (HMemory 公开 API)                        │
├─────────────────────────────────────────────────────────────┤
│                     队列引擎                                │
│               (读优先异步调度)                              │
├─────────────────────────────────────────────────────────────┤
│                     搜索评分器                              │
│              (相似度 × 时间衰减评分)                        │
├─────────────────────────────────────────────────────────────┤
│                     存储引擎                                │
│              (LanceDB + 标量索引)                           │
├─────────────────────────────────────────────────────────────┤
│                  分层驱逐策略                               │
│         (精确 < 10K 记录 / 阈值 >= 10K)                     │
└─────────────────────────────────────────────────────────────┘
```

### 🎯 使用场景

- **RAG 系统** - LLM 的检索增强生成
- **知识库** - 语义文档搜索
- **AI Agent 记忆** - 持久化对话上下文
- **代码智能** - 语义代码搜索
- **笔记管理** - 智能笔记检索

### 🤝 参与贡献

我们欢迎贡献！请参阅 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 了解贡献指南。

---

## License

MIT © HMemory Contributors