palacelite 0.3.0__tar.gz

palacelite-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fajknli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

palacelite-0.3.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: palacelite
+Version: 0.3.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: chromadb>=1.5.0
+Requires-Dist: sentence-transformers>=5.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+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.3.0-blue)](https://github.com/fajknli/palacelite/releases)
+
+轻量级 AI 记忆系统，灵感来自MemPalace。默认离线运行，数据完全本地化。
+
+## 核心概念
+
+采用三层结构组织记忆：**Wing**（项目或人）→ **Room**（具体话题）→ **Drawer**（记忆条目）。每条记忆存储原文和向量，支持混合检索（向量相似度 + 时间衰减 + 重要性加权）。
+
+## 安装
+
+```bash
+git clone https://github.com/fajknli/palacelite.git
+cd palacelite
+pip install -e .
+pip install -r requirements.txt
+```
+
+首次使用需下载嵌入模型（约百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

palacelite-0.3.0/README.md

@@ -0,0 +1,125 @@
+# 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.3.0-blue)](https://github.com/fajknli/palacelite/releases)
+
+轻量级 AI 记忆系统，灵感来自MemPalace。默认离线运行，数据完全本地化。
+
+## 核心概念
+
+采用三层结构组织记忆：**Wing**（项目或人）→ **Room**（具体话题）→ **Drawer**（记忆条目）。每条记忆存储原文和向量，支持混合检索（向量相似度 + 时间衰减 + 重要性加权）。
+
+## 安装
+
+```bash
+git clone https://github.com/fajknli/palacelite.git
+cd palacelite
+pip install -e .
+pip install -r requirements.txt
+```
+
+首次使用需下载嵌入模型（约百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

palacelite-0.3.0/palacelite/__init__.py

@@ -0,0 +1,7 @@
+"""PalaceLite - 轻量级 AI 记忆系统"""
+
+from .core import PalaceLite
+from .models import Drawer, Room, SearchResult, Wing
+
+__version__ = "0.3.0"
+__all__ = ["PalaceLite", "Wing", "Room", "Drawer", "SearchResult"]

palacelite-0.3.0/palacelite/cli.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+PalaceLite 命令行工具
+
+用法:
+    palacelite add --wing <wing> --room <room> --content "记忆内容"
+    palacelite search --query "搜索内容"
+    palacelite list --wing <wing>
+    palacelite stats
+"""
+
+from datetime import datetime
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from .core import PalaceLite
+
+console = Console()
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def cli():
+    """PalaceLite - 轻量级 AI 记忆系统"""
+
+
+@cli.command()
+@click.option("--wing", "-w", required=True, help="Wing 名称（项目或人）")
+@click.option("--room", "-r", required=True, help="Room 名称（话题）")
+@click.option("--content", "-c", required=True, help="记忆内容")
+@click.option("--tags", "-t", help="标签，逗号分隔")
+@click.option("--importance", "-i", default=1, help="重要性（1-10）")
+def add(wing, room, content, tags, importance):
+    """添加记忆"""
+    p = PalaceLite()
+
+    # 确保 wing 存在
+    if not p.get_wing(wing):
+        p.add_wing(wing)
+        console.print(f"[yellow]自动创建 Wing: {wing}[/yellow]")
+
+    # 确保 room 存在
+    if not p.get_room(wing, room):
+        p.add_room(wing, room)
+        console.print(f"[yellow]自动创建 Room: {wing}/{room}[/yellow]")
+
+    tag_list = tags.split(",") if tags else []
+    drawer = p.add_memory(content, wing, room, tag_list, importance)
+
+    console.print(f"[green]✓[/green] 已添加记忆 (id: {drawer.id[:8]}...)")
+
+
+@cli.command()
+@click.option("--query", "-q", required=True, help="搜索内容")
+@click.option("--wing", "-w", help="限定 Wing")
+@click.option("--room", "-r", help="限定 Room（需与 --wing 一起使用）")
+@click.option("--top", "-k", default=5, help="返回结果数量")
+def search(query, wing, room, top):
+    """搜索记忆"""
+    p = PalaceLite()
+
+    if wing and room:
+        results = p.search_by_room(query, wing, room, top)
+        title = f"在 {wing}/{room} 中搜索: {query}"
+    elif wing:
+        results = p.search_by_wing(query, wing, top)
+        title = f"在 {wing} 中搜索: {query}"
+    else:
+        results = p.search(query, top_k=top)
+        title = f"搜索: {query}"
+
+    if not results:
+        console.print("[yellow]未找到相关记忆[/yellow]")
+        return
+
+    table = Table(title=title)
+    table.add_column("#", style="dim")
+    table.add_column("位置", style="cyan")
+    table.add_column("记忆内容", style="white")
+    table.add_column("得分", style="green")
+
+    for i, r in enumerate(results, 1):
+        location = f"{r.wing_name}/{r.room_name}"
+        content = r.drawer.content[:80] + ("..." if len(r.drawer.content) > 80 else "")
+        table.add_row(str(i), location, content, f"{r.score:.3f}")
+
+    console.print(table)
+
+
+@cli.command()
+@click.option("--wing", "-w", help="限定 Wing")
+@click.option("--room", "-r", help="限定 Room（需与 --wing 一起使用）")
+def list(wing, room):
+    """列出记忆"""
+    p = PalaceLite()
+
+    if wing and room:
+        memories = p.list_memories(wing, room)
+        title = f"记忆列表: {wing}/{room}"
+    elif wing:
+        memories = p.list_memories(wing)
+        title = f"记忆列表: {wing}"
+    else:
+        memories = p.list_memories()
+        title = "所有记忆"
+
+    if not memories:
+        console.print("[yellow]没有记忆[/yellow]")
+        return
+
+    table = Table(title=title)
+    table.add_column("ID", style="dim")
+    table.add_column("位置", style="cyan")
+    table.add_column("记忆内容", style="white")
+    table.add_column("重要性", style="green")
+
+    for m in memories[:20]:
+        # 获取位置
+        room_obj = p.get_room_by_id(m.room_id)
+        if room_obj:
+            wing_obj = p.get_wing_by_id(room_obj.wing_id)
+            wing_name = wing_obj.name if wing_obj else "?"
+            room_name = room_obj.name
+        else:
+            wing_name = "?"
+            room_name = "?"
+
+        content = m.content[:60] + ("..." if len(m.content) > 60 else "")
+        table.add_row(m.id[:8], f"{wing_name}/{room_name}", content, str(m.importance))
+
+    console.print(table)
+
+
+@cli.command()
+def stats():
+    """显示统计信息"""
+    p = PalaceLite()
+    stats = p.stats()
+
+    panel = Panel(
+        f"[bold]Wings:[/bold] {stats['wings']}\n"
+        f"[bold]Rooms:[/bold] {stats['rooms']}\n"
+        f"[bold]Drawers:[/bold] {stats['drawers']}\n"
+        f"[bold]总重要性:[/bold] {stats['total_importance']}\n"
+        f"[bold]数据库大小:[/bold] {stats['db_size_bytes'] / 1024:.1f} KB\n"
+        f"[bold]工作目录:[/bold] {stats['workspace']}",
+        title="PalaceLite 统计",
+        border_style="green",
+    )
+    console.print(panel)
+
+
+@cli.command()
+@click.option("--days", "-d", default=90, help="归档超过多少天的记忆")
+@click.option("--importance", "-i", default=2, help="重要性低于此值的记忆")
+def archive_old(days, importance):
+    """归档旧记忆"""
+    p = PalaceLite()
+    count = p.archive_old_memories(min_importance=importance, days_old=days)
+    console.print(f"[green]✓ 已归档 {count} 条记忆[/green]")
+
+
+@cli.command()
+def list_archived():
+    """列出已归档的记忆"""
+    p = PalaceLite()
+    memories = p.list_archived_memories()
+
+    if not memories:
+        console.print("[yellow]没有已归档的记忆[/yellow]")
+        return
+
+    table = Table(title="已归档的记忆")
+    table.add_column("#", style="dim")
+    table.add_column("ID", style="dim")
+    table.add_column("内容", style="white")
+
+    for i, m in enumerate(memories[:20], 1):
+        content = m.content[:60] + ("..." if len(m.content) > 60 else "")
+        table.add_row(str(i), m.id[:8], content)
+
+    console.print(table)
+
+
+@cli.command()
+@click.option("--output", "-o", help="输出文件路径（可选，默认自动生成）")
+def export_archived(output):
+    """导出已归档的记忆到 JSON"""
+    p = PalaceLite()
+    count, path = p.export_archived_memories(output)
+    console.print(f"[green]已导出 {count} 条记忆到 {path}[/green]")
+
+
+@cli.command()
+@click.confirmation_option(prompt="确定要永久删除所有已归档的记忆吗？")
+def delete_archived():
+    """永久删除已归档的记忆"""
+    p = PalaceLite()
+    count = p.delete_archived_memories()
+    console.print(f"[green]✓ 已永久删除 {count} 条记忆[/green]")
+
+
+@cli.command()
+def wings():
+    """列出所有 Wing"""
+    p = PalaceLite()
+    wings = p.list_wings()
+
+    if not wings:
+        console.print("[yellow]没有 Wing[/yellow]")
+        return
+
+    table = Table(title="Wings 列表")
+    table.add_column("名称", style="cyan")
+    table.add_column("类型", style="green")
+    table.add_column("创建时间", style="dim")
+
+    for w in wings:
+        created = datetime.fromtimestamp(w.created_at).strftime("%Y-%m-%d %H:%M")
+        table.add_row(w.name, w.type, created)
+
+    console.print(table)
+
+
+@cli.command()
+@click.argument("wing_name")
+def rooms(wing_name):
+    """列出指定 Wing 下的 Rooms"""
+    p = PalaceLite()
+    rooms = p.list_rooms(wing_name)
+
+    if not rooms:
+        console.print(f"[yellow]Wing '{wing_name}' 下没有 Room[/yellow]")
+        return
+
+    table = Table(title=f"Rooms 列表: {wing_name}")
+    table.add_column("名称", style="cyan")
+    table.add_column("创建时间", style="dim")
+
+    for r in rooms:
+        created = datetime.fromtimestamp(r.created_at).strftime("%Y-%m-%d %H:%M")
+        table.add_row(r.name, created)
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    cli()