Metadata-Version: 2.4
Name: qmemory
Version: 0.1.1
Summary: Local long-term memory service for AI agents — simple API, single SQLite file, fully local.
Project-URL: Homepage, https://gitee.com/huizhou-shunshi-intelligent/qmemory
Project-URL: Repository, https://gitee.com/huizhou-shunshi-intelligent/qmemory
Project-URL: Issues, https://gitee.com/huizhou-shunshi-intelligent/qmemory/issues
Author-email: QLogicAgent <dev@qlogicagent.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,embedding,local,memory,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jieba>=0.42
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.7
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: client
Requires-Dist: httpx>=0.27; extra == 'client'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# QMemory

本地长期记忆服务，面向 AI agent、桌面助手和需要单机记忆层的应用；本地仅保留 embedding 与 reranker，语义决策依赖远端大模型。

**QMemory = 独立本地记忆服务 · 极简公共 API · 单文件 SQLite · 单进程。**

[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

## 项目状态

- 当前版本：`0.1.0`
- 当前仓库状态：可开发、可本地运行、可独立验证
- 发布状态：仓库已公开；PyPI 首发尚未完成
- 当前模型口径：仅保留本地 embedding 与本地 reranker；不再内置本地 LLM provider

## 核心能力

- 极简公共 API：`add / search / get_all / get / update / delete / delete_all / health`
- 本地数据面：单 SQLite 文件，无需 Postgres、Redis 或外部向量库；embedding 与 reranker 本地运行
- 混合检索：向量搜索 + FTS5 + 时间过滤，RRF 融合
- 多语言检索：本地 embedding 已支持多语言模型切换，当前推荐 `multilingual-e5-small`，并保留中文场景优化路径
- 语义决策：抽取、规划、冲突判断、consolidation 等统一走远端大模型
- 结构化记忆：支持冲突处理、关系链、画像、层级检索与时间推理增强
- 可迁移：内置 `.qmem` 导入导出链路

## 架构概览

```
clients / adapters / sdk
          |
          v
  FastAPI server (:18800)
          |
  ingest / recall / profile / manage
          |
  SQLite + FTS5 + local embedding + local reranker
          |
  remote LLM for semantic decisions
```

## 安装

当前建议直接从源码安装：

```bash
git clone git@gitee.com:huizhou-shunshi-intelligent/qmemory.git
cd qmemory
pip install -e .
```

开发环境：

```bash
pip install -e ".[dev]"
```

## 快速开始

启动服务：

```bash
qmemory serve
```

自定义端口和数据库：

```bash
qmemory serve --host 127.0.0.1 --port 18800 --db ./memory.db
```

导出与导入：

```bash
qmemory export --output backup.qmem
qmemory import backup.qmem --merge
```

## Python 调用示例

```python
from qmemory import QMemoryClient

client = QMemoryClient(base_url="http://localhost:18800")

client.add(
    user_id="alice",
    messages=[
        {"role": "user", "content": "我刚从腾讯跳到字节做后端"},
        {"role": "assistant", "content": "恭喜，听起来是个不错的变化。"},
    ],
)

result = client.search(query="用户现在在哪里工作？", user_id="alice")
print(result["context"])
```

## 公共 API

```
POST   /v1/memories/
GET    /v1/memories/search/
GET    /v1/memories/
GET    /v1/memories/{id}/
PUT    /v1/memories/{id}/
DELETE /v1/memories/{id}/
DELETE /v1/memories/
GET    /v1/health/
```

## 配置与运行约定

常见环境变量：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `QMEMORY_PORT` | `18800` | 服务端口 |
| `QMEMORY_DB_PATH` | `~/.qmemory/memory.db` | 数据库路径 |
| `QMEMORY_API_KEY` | 空 | 公共 API 鉴权 |
| `QMEMORY_ADMIN_KEY` | 空 | 管理 API 鉴权 |

Embedding 说明：

- 当前架构已支持多语言本地 embedding 切换
- 推荐默认模型：`Alibaba-NLP/gte-multilingual-base`
- 中文高密度场景仍可切回 `bge-small-zh-v1.5`
- FTS 路径已按语言拆分为中文 / 英文检索路由

Reranker / LLM 说明：

- 本地 reranker 仅负责召回结果重排
- 本地 LLM 已从仓库中移除，不再作为可选能力
- 抽取、规划、冲突判断、consolidation 等语义决策统一走远端大模型

## 模型资产发布方案

QMemory 的两个大模型不进入 Git 历史，统一走“manifest + 下载脚本 + release 资产”方案。

- 清单文件：`models-manifest.json`
- 下载脚本：`scripts/download_models.py`
- 默认安装目录：`~/.qmemory/models`
- 推荐发布方式：把模型打成独立 `tar.gz` 附件，挂到同版本 Gitee Release

列出 manifest 中的模型：

```bash
python scripts/download_models.py --list
```

按 manifest 下载模型到默认目录：

```bash
python scripts/download_models.py
```

只校验本地模型是否齐全：

```bash
python scripts/download_models.py --check
```

把已下载模型打成 release 附件：

```bash
python scripts/download_models.py --release-tag v0.1.1 --archive-dir dist/model-release-assets
```

如果你已经把模型附件挂在某个 Gitee Release 页面或对象存储下，可以优先从 release 资产下载：

```bash
set QMEMORY_MODELS_RELEASE_BASE_URL=https://example.com/qmemory/v0.1.1
python scripts/download_models.py --release-tag v0.1.1 --channel auto
```

`build_exe.py --download` 现在也会复用这条 manifest 驱动的下载链路。

## Gitee Tag 发布

Tag 发布操作说明见 [GITEE_RELEASE.md](GITEE_RELEASE.md)。

## 评测

评测仓库见 [qmemory-bench](https://gitee.com/huizhou-shunshi-intelligent/qmemory-bench)。

当前设计目标：

- LongMemEval-S ≥ 90%
- LoCoMo 复杂检索显著优于扁平记忆
- 中文与时间推理场景可稳定验证

## 开发与测试

```bash
pytest
```

仓库内包含：

- FastAPI 服务端
- SQLite schema 与 migration
- Recall / ingest / consolidation 核心管线
- adapter-claw 与 adapter-mcp
- 完整测试集

## 许可证

当前仓库内已提交内容使用 [Apache-2.0](LICENSE)。

设计文档中提到的商业化 / Pro 规划尚未在本仓库中以独立许可证文件落地，因此本仓库首发以当前实际代码许可为准。

更多发布说明见 [CHANGELOG.md](CHANGELOG.md)、[RELEASE_NOTES_v0.1.1.md](RELEASE_NOTES_v0.1.1.md) 和 [OPEN_SOURCE_STATUS.md](OPEN_SOURCE_STATUS.md)。
