Metadata-Version: 2.4
Name: palacelite
Version: 0.4.0
Summary: 轻量级 AI 记忆系统
Author: fajknli
Project-URL: Changelog, https://github.com/fajknli/palacelite/blob/main/CHANGELOG.md
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: sentence-transformers>=5.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: chat
Requires-Dist: llama-cpp-python>=0.3.0; extra == "chat"
Dynamic: license-file

# PalaceLite

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-0.4.0--dev-blue)](https://github.com/fajknli/palacelite/releases)
[![PyPI version](https://badge.fury.io/py/palacelite.svg)](https://pypi.org/project/palacelite/)

轻量级 AI 记忆系统，灵感来自MemPalace。默认离线运行，数据完全本地化。

## 核心概念

采用三层结构组织记忆：**Wing**（项目或人）→ **Room**（具体话题）→ **Drawer**（记忆条目）。每条记忆存储原文和向量，支持混合检索（向量相似度 + 时间衰减 + 重要性加权）。

## 安装

```bash
git clone https://github.com/fajknli/palacelite.git
cd palacelite
pip install -e .
pip install -r requirements.txt
```
或者:

```bash
pip install palacelite
```


首次使用需下载嵌入模型（约百MB，BAAI/bge-small-zh-v1.5），添加 `--online` 参数即可自动下载，之后可永久离线运行。

## 快速开始

### CLI

```bash
# 添加记忆
palacelite add -w default -r chat -c "用户喜欢 PostgreSQL"

# 搜索
palacelite search -q "数据库"

# 列出活跃记忆
palacelite list

# 归档超过90天且重要性低于2的记忆
palacelite archive-old --days 90 --importance 2

# 导出已归档记忆（自动保存到 ~/.palacelite/exports/）
palacelite export-archived

# 永久删除已归档记忆
palacelite delete-archived

# 统计
palacelite stats
```

### Python API

```python
from palacelite import PalaceLite

p = PalaceLite()  # 默认离线，offline=False 可联网下载模型

p.add_memory("用户喜欢 PostgreSQL", "default", "chat")
results = p.search("数据库")
context = p.build_context("数据库选型")  # 构建 LLM 上下文
```

验证安装:

```bash
python -c "from palacelite import PalaceLite; print('OK')"
```

### 带记忆对话

`examples/` 目录提供了完整的对话示例：

```bash
# 离线模式（默认）
python examples/chat.py -m /path/to/model.gguf

# 联网模式（首次下载嵌入模型）
python examples/chat.py -m /path/to/model.gguf --online

# 指定 GPU 层数
python examples/chat.py -m /path/to/model.gguf -g 30
```

对话命令：`/help`、`/mem`、`/list`、`/stats`、`/clear`、`/quit`。

## 命令速查

| 命令 | 说明 |
|------|------|
| `add -w <wing> -r <room> -c <内容>` | 添加记忆 |
| `search -q <关键词>` | 搜索记忆 |
| `list [-w wing] [-r room]` | 列出活跃记忆 |
| `archive-old [--days 90] [--importance 2]` | 批量归档旧记忆 |
| `list-archived` | 列出已归档记忆 |
| `export-archived [-o 路径]` | 导出归档到 JSON |
| `delete-archived` | 永久删除归档记忆 |
| `stats` | 显示统计信息 |
| `wings` | 列出所有 Wing |
| `rooms <wing>` | 列出指定 Wing 下的 Room |

## 配置

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `PALACE_MODEL_PATH` | - | GGUF 模型文件路径 |
| `PALACE_MODEL_DIR` | `~/Public/ai/models` | 模型存放目录 |
| `GPU_LAYERS` | `20` | GPU 加速层数 |

工作目录默认为 `~/.palacelite`，可通过 `PalaceLite(workspace="/path")` 自定义。

## 数据维护

导出数据清洗（用于微调）：
```bash
python scripts/clean_memories.py ~/backup.json ~/cleaned.json
```

更换嵌入模型后重建向量库：
```bash
python scripts/rebuild_embeddings.py
```

## 许可证

MIT
