qmemory 0.1.1

Local long-term memory service for AI agents — simple API, single SQLite file, fully local.

QMemory

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

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

项目状态

• 当前版本：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

安装

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

git clone [e-mail]:huizhou-shunshi-intelligent/qmemory.git
cd qmemory
pip install -e .

开发环境：

pip install -e ".[dev]"

快速开始

启动服务：

qmemory serve

自定义端口和数据库：

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

导出与导入：

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

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 中的模型：

python scripts/download_models.py --list

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

python scripts/download_models.py

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

python scripts/download_models.py --check

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

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

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

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。

评测

评测仓库见 qmemory-bench。

当前设计目标：

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

开发与测试

pytest

仓库内包含：

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

许可证

当前仓库内已提交内容使用 Apache-2.0。

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

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