Metadata-Version: 2.4
Name: palacelite
Version: 0.5.2
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

好的，我来把新增的 CLI 命令和对话内命令补充到 README 中，并修复那个失效的 PyPI 徽章链接。

这是更新后的 README 内容，你可以直接复制使用。

# 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/)
[![PyPI version](https://badge.fury.io/py/palacelite.svg)](https://pypi.org/project/palacelite/)

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

## 安装

```bash
pip install palacelite
```

首次使用需下载嵌入模型（约 100MB），添加 `--online` 参数即可自动下载，之后可永久离线运行：

```bash
palacelite chat -m /path/to/model.gguf --online
```

## 核心概念

采用三层结构组织记忆：

- **Wing**：项目或人
- **Room**：具体话题
- **Drawer**：记忆条目

系统首次运行自动创建默认 Wings：`work`、`life`、`tech`、`unsorted`，每个 Wing 下默认 Room 为 `general`。

每条记忆存储原文和向量，支持混合检索（向量相似度 + 关键词匹配 + 时间衰减 + 重要性加权）。

## 快速开始

### CLI 命令

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

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

# 带记忆对话
palacelite chat -m /path/to/model.gguf

# 列出活跃记忆（带序号、ID和时间）
palacelite list -l 30

# 紧凑显示记忆ID（便于复制移动）
palacelite list-ids -l 20

# 统计信息
palacelite stats
```

### Python API

```python
from palacelite import PalaceLite

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

# 添加记忆
p.add_memory("用户喜欢 PostgreSQL", "work", "general")

# 搜索
results = p.search("数据库")

# 构建 LLM 上下文
context = p.build_context("数据库选型")
```

### 对话模式

```bash
# 首次使用（下载嵌入模型）
palacelite chat -m /path/to/model.gguf --online

# 日常使用（默认进入 unsorted/general）
palacelite chat -m /path/to/model.gguf

# 指定 Wing 和 Room
palacelite chat -m /path/to/model.gguf -w work -r general

# 指定 GPU 层数
palacelite chat -m /path/to/model.gguf -g 30

# 使用提炼模型压缩记忆（推荐 3B 小模型，如 Qwen2.5-3B-Instruct）
palacelite chat -m /path/to/model.gguf --distiller-model /path/to/small.gguf

# 手动指定 prompt 模板（支持 qwen/gemma/llama/mistral）
palacelite chat -m /path/to/model.gguf --prompt-template qwen
```

## CLI 命令速查

### 记忆操作

| 命令 | 说明 |
|------|------|
| `add -w <wing> -r <room> -c <内容>` | 添加记忆 |
| `search -q <关键词> [-w wing] [-r room]` | 搜索记忆 |
| `list [-w wing] [-r room] [-l 数量] [-a]` | 列出活跃记忆 |
| `list-ids [-w wing] [-r room] [-l 数量]` | 紧凑显示记忆ID，便于复制 |
| `move -i <id> [-w wing] [-r room]` | 移动单条记忆 |
| `move -i <id1> -i <id2> [-w wing] [-r room]` | 移动范围内记忆 |
| `move-all -fw <wing> [-fr room] -tw <wing> -tr <room>` | 批量移动记忆 |

### Wing 管理

| 命令 | 说明 |
|------|------|
| `wing add <名称> [-t project\|person]` | 添加 Wing |
| `wing list` | 列出所有 Wing |
| `wing remove <名称> [--force]` | 删除 Wing（需先迁移记忆） |

### Room 管理

| 命令 | 说明 |
|------|------|
| `room add <wing> <名称>` | 添加 Room |
| `room list [wing]` | 列出 Room |
| `room remove <wing> <名称> [--force]` | 删除 Room（需先迁移记忆） |

### 归档操作

| 命令 | 说明 |
|------|------|
| `archive-old [--days 90] [--importance 2]` | 批量归档旧记忆 |
| `list-archived` | 列出已归档记忆 |
| `export-archived [-o 路径]` | 导出归档记忆到 JSON |
| `delete-archived` | 永久删除归档记忆 |

### 系统命令

| 命令 | 说明 |
|------|------|
| `chat -m <模型路径>` | 启动对话 |
| `stats` | 显示统计信息 |

## 对话内命令速查

### 记忆操作

| 命令 | 别名 | 说明 |
|------|------|------|
| `/mem <关键词>` | - | 搜索记忆 |
| `/add <内容>` | - | 手动添加记忆 |
| `/list [数量]` | `/ls` | 列出最近记忆 |
| `/move <id> [id2] [wing]/[room]` | `/mv` | 移动记忆 |

### 空间管理

| 命令 | 别名 | 说明 |
|------|------|------|
| `/wings` | `/w` | 列出所有 Wing，高亮当前 |
| `/wing add <名称> [类型]` | - | 添加 Wing |
| `/wing remove <名称>` | - | 提示迁移，引导至 CLI |
| `/rooms [wing]` | `/r` | 列出 Room，高亮当前 |
| `/room add <名称>` | - | 在当前 Wing 添加 Room |
| `/room remove <名称>` | - | 提示迁移，引导至 CLI |
| `/cd` | - | 查看当前位置 |
| `/cd [wing]/[room]` | - | 切换到指定 Room |
| `/cd [room]` | - | 在当前 Wing 下切换 Room |

### 系统命令

| 命令 | 别名 | 说明 |
|------|------|------|
| `/stats` | - | 显示统计信息 |
| `/clear` | - | 清屏 |
| `/help` | - | 显示帮助 |
| `/quit` | `/q`, `/exit` | 退出对话 |

## 记忆维护

### 数据清洗与重建

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

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

## 配置

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

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

## 架构

当前版本 (0.5.2) 已完成：

- SQLite-vec 向量存储，无需外部向量数据库
- 异步记忆提炼（Distiller），支持技术参数原样保留
- 混合检索：向量相似度 + 关键词匹配 + 时间衰减 + 重要性加权
- 系统初始化：首次运行自动创建默认 Wings 和 Rooms
- 完整空间管理：CLI 和对话内增删查改 Wing/Room
- 记忆移动：单条、范围和全量移动，智能默认值
- 自动分类：基于关键词规则将记忆归类到 work/life/tech/unsorted
- 关系图谱 Schema（relations、patrol_queue），为后续版本做准备
- 记忆归档与导出
- 自动 prompt 模板检测

## 许可证

MIT
