# AIMemoryDB-Embedded

**Repository Path**: fbcha/aimemorydb-embedded

## Basic Information

- **Project Name**: AIMemoryDB-Embedded
- **Description**: AIMemoryDB Embedded 是一个嵌入式 AI 记忆系统数据库，专为需要本地向量存储、语义搜索和知识图谱管理的应用场景设计。仅依赖 `numpy`，零外部服务，即装即用。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIMemoryDB Embedded

[![CI](https://github.com/fbcha/AIMemoryDB-Embedded/actions/workflows/ci.yml/badge.svg)](https://github.com/fbcha/AIMemoryDB-Embedded/actions/workflows/ci.yml)

AIMemoryDB Embedded 是一个嵌入式 AI 记忆系统数据库，专为需要本地向量存储、语义搜索和知识图谱管理的应用场景设计。仅依赖 `numpy`，零外部服务，即装即用。

与传统数据库不同，AIMemoryDB 不仅存储结构化数据，还能理解内容的语义含义，支持向量相似度搜索、全文检索和知识图谱遍历的混合查询。适用于聊天机器人记忆、RAG 应用、知识管理、智能体上下文管理等场景。

```python
from aimemorydb import AIMemoryDB

db = AIMemoryDB("./data")
mid = db.add("人工智能是让机器具有智能的技术", tags=["AI"])
results = db.search("什么是AI？", top_k=5)
for r in results:
    print(f"[{r.rank}] {r.content[:40]}... score={r.score:.3f}")
```

## 安装

```bash
git clone https://github.com/fbcha/AIMemoryDB-Embedded.git
cd aimemorydb
pip install -e ".[full]"
```

可选依赖：

```bash
pip install -e ".[encryption]"   # Fernet 加密支持
pip install -e ".[tokenizer]"    # jieba 中文分词
```

> PyPI 发布即将到来。届时可通过 `pip install aimemorydb-embedded` 一键安装。

## 核心能力

| 功能 | 说明 |
|------|------|
| **向量搜索** | HNSW 索引 (L2/IP/Cosine)，可选 PQ 量化 |
| **全文搜索** | BM25 倒排索引，ngram/jieba/char 分词，短语/模糊搜索 |
| **图存储** | 有向图，边属性，多跳遍历 |
| **混合检索** | 向量 + BM25 + 图 RRF 融合搜索 |
| **持久化** | WAL（分段二进制 + CRC32）+ 二进制快照 |
| **分层存储** | 热/温/冷三层自动迁移 |
| **分区架构** | 分区并行搜索，无限水平扩展 |
| **TTL 自动过期** | `add(ttl=...)` 设置存活时间，`get()/search()` 惰性清理 |
| **命名空间** | `add(namespace=...)` + `search(namespace=...)` 元数据过滤隔离 |
| **运行时配置** | `update_config(faiss_index_factory=..., enable_ttl=...)` |
| **索引重建** | `rebuild_indices()` 一键重建全文+图索引 |
| **快照管理** | `list_snapshots()` / `delete_snapshot()` |
| **指标导出** | `export_metrics_prometheus()` / `export_metrics_json()` |
| **备份加密** | `backup(encryption_key=...)` / `restore(encryption_key=...)` |
| **CQL 增强** | `ORDER BY` / `LIMIT` / `SET` 子句 |
| **安全** | Fernet 加密（可选），审计日志链，RBAC |
| **图查询** | Cypher-like CQL（MATCH/CREATE/DELETE/WHERE/ORDER BY/LIMIT/SET） |
| **监控** | Metrics 注册表，结构化 JSON 日志，链路追踪 |

## 进阶用法

### TTL 自动过期

```python
mid = db.add("临时内容", ttl=60)  # 60 秒后自动过期
mem = db.get(mid)                  # 如果已过期返回 None
```

### 命名空间隔离

```python
db.add("用户A数据", namespace="user_a")
results = db.search("查询", namespace="user_a")  # 只搜索 user_a
```

### 运行时配置更新

```python
db.update_config(faiss_index_factory="HNSW64,Flat", enable_ttl=False)
```

### 索引重建

```python
db.rebuild_indices()  # 重建全文索引和图索引
```

### 指标导出

```python
prometheus = db.export_metrics_prometheus()
json_data = db.export_metrics_json()
```

### 加密备份

```python
key = b"..."  # 32 字节密钥
db.backup(encryption_key=key)
db.restore("backup.snap", encryption_key=key)
```

### CQL 增强

```cypher
MATCH (n)
RETURN n.content, n.importance
ORDER BY n.importance DESC
LIMIT 5

MATCH (n)
SET n.importance = 1.0
WHERE n.id = "mem_123"
```

## 安装验证

```bash
python -c "from aimemorydb import AIMemoryDB; print('ok')"
```

## 开发

```bash
pip install -e ".[full]"
pytest
ruff check src/ tests/
```

## 兼容性

- Python >= 3.11
- 仅依赖 `numpy`（可选：`cryptography`、`jieba`）
- 跨平台（Windows / Linux / macOS）