LocalMemOS

本地 LLM 记忆中间件: 在速度与准确性之间取得平衡, 为 Claude Desktop、Cursor 等提供可检索的长期记忆.

---

特性

• 速度与准确性兼顾: 三级检索 (关键词 + 全文 + 图谱向量) 组合, 毫秒级召回同时保持事实一致
• Read-Before-Write: 写入前检索、去重与冲突检测, 减少幻觉与重复
• MCP 接入: 通过 Model Context Protocol 暴露给 Claude Desktop、Cursor 等
• 待审池: 高重要性事实先入待审, 审阅后再写入图谱, 支持可选自动复核

---

下载

git clone https://github.com/Cocoblood9527/LocalMemOS.git
cd LocalMemOS

---

安装

需要: Python 3.10+

在项目根目录执行:

# 1. 创建虚拟环境
python3 -m venv .venv

# 2. 激活虚拟环境
# Linux / macOS:
source .venv/bin/activate
# Windows (CMD):
#   .venv\Scripts\activate.bat
# Windows (PowerShell):
#   .venv\Scripts\Activate.ps1

# 3. 安装依赖
pip install -r requirements.txt
# 国内用户可改用清华源更快: pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 安装 Web 服务依赖 (用于启动聊天与设定页)
pip install fastapi uvicorn
# 国内用户可改用清华源更快: pip install fastapi uvicorn -i https://pypi.tuna.tsinghua.edu.cn/simple

# 5. 首次使用: 在浏览器打开设定页, 按「1. 安装与运行环境」→「1.1 首次使用步骤说明」完成初始化

---

使用 (推荐: Web 端)

一条命令启动, 用浏览器即可聊天和完成所有配置:

python manage.py serve

(若未激活 venv, 用 ./.venv/bin/python manage.py serve 或 Windows 下 .venv\Scripts\python.exe manage.py serve.)

启动后在浏览器打开:

页面	地址	说明
聊天	http://127.0.0.1:8765/	左栏对话, 右栏展示 MCP 调用与审计
设定	http://127.0.0.1:8765/settings.html	数据库维护、配置 (LLM/Embedding)、待审池、环境与初始化

首次使用请在设定页进入「1. 安装与运行环境」→「1.1 首次使用步骤说明」, 按向导完成目录与配置文件创建、LLM/Embedding 配置及环境检查.

---

终端方式 (可选)

若更习惯命令行, 可使用:

• 管理 (配置 / 待审 / 数据库 / 环境): python manage.py 进入分层菜单, 或子命令如 python manage.py config show、python manage.py pending show.
• 仅启动对话 (不启动 Web): python main.py — 在项目根、已激活虚拟环境的前提下运行.

---

在 Cursor / Claude Desktop 中使用 (MCP)

在 MCP 配置中挂载本项目的 MCP 服务: 工作目录 (cwd) 必须为项目根, 命令为用项目虚拟环境中的 Python 直接运行 api/mcp_server.py.

推荐配置:

• command: 项目内 Python 解释器绝对路径 (例如 .venv/bin/python 或 Windows 下 .venv\Scripts\python.exe)
• args: ["api/mcp_server.py"]
• cwd: 项目根目录绝对路径

桌面应用若不继承终端 PATH, 务必使用上述绝对路径. 若客户端只支持单一「命令」输入框, 可填: 项目根/.venv/bin/python api/mcp_server.py (或 Windows: 项目根\.venv\Scripts\python.exe api/mcp_server.py), 并确保工作目录为项目根.

---

更多说明

• 配置: LLM、Embedding、图查询跳数等可在 设定页 的「3. 配置」中完成, 或通过 python manage.py 菜单 3.x 与 manage.py config --help 在终端修改. 存储层 (Kuzu 重试次数/退避、SQLite 锁等待超时) 可在 config/settings.yaml 的 storage 段或环境变量 LOCALMEMOS_KUZU_INIT_*、LOCALMEMOS_SQLITE_TIMEOUT 配置.
• 待审事实: 高优事实先入待审池, 在设定页「2. 数据与待审」→「2.3 待审池」查看简报、应用或自动复核; 终端可用 python manage.py pending digest、pending apply 等.
• 记忆库 GC: 对话与图谱支持置信度与访问统计; 长期未访问或低置信度可由 python manage.py memory gc 归档 (对话软归档, 图谱边删除). 可配合 cron 定期执行; 策略见 config/settings.yaml 的 gc 段或环境变量 LOCALMEMOS_GC_*.
• 统一记忆服务: python manage.py serve 启动后, Web 聊天/设定与 MCP 共用同一数据源, 避免多端脑裂.
• 技术细节: 见各模块注释或 python manage.py --help.

---

测试

python -m unittest discover -s tests -v

---

许可证

见仓库根目录 LICENSE 文件 (GPL-3.0).