# https://github.com/qualixar/superlocalmemory 项目说明书
生成时间：2026-05-30 18:04:33 UTC
## 目录
- [首页](#page-home)
- [快速入门](#page-getting-started)
- [V3 架构](#page-architecture)
- [三种运行模式详解](#page-modes)
- [CLI 参考手册](#page-cli-reference)
- [MCP 工具集](#page-mcp-tools)
- [检索管道](#page-retrieval-pipeline)
- [记忆生命周期](#page-memory-lifecycle)
- [多机 Mesh 网络](#page-multi-machine)
- [配置参考](#page-configuration)
## 首页
### 相关页面
相关主题：[快速入门](#page-getting-started), [V3 架构](#page-architecture), [三种运行模式详解](#page-modes)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/qualixar/superlocalmemory/blob/main/README.md)
- [package.json](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
- [src/superlocalmemory/__init__.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/__init__.py)
- [src/superlocalmemory/server/api.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/api.py)
- [src/superlocalmemory/server/ui.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
- [src/superlocalmemory/cli/main.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
- [src/superlocalmemory/server/routes/chat.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/routes/chat.py)
- [wiki-content/v2-archive/README.md](https://github.com/qualixar/superlocalmemory/blob/main/wiki-content/v2-archive/README.md)
# 首页
SuperLocalMemory 是一个本地优先（Local-First）的 AI 代理记忆系统，专为大语言模型（LLM）设计，用于持久化存储、检索和管理知识记忆。该系统基于信息几何学原理构建，提供数学保证的检索质量，支持完全离线的本地部署，确保用户数据的隐私与主权。
## 项目概述
SuperLocalMemory 由 Varun Pratap Bhardwaj 开发，采用 AGPL-3.0 开源许可证。项目核心特性包括：
- **四通道检索架构**：语义检索、词法检索、时间检索和结构检索的融合
- **Fisher-Rao 相似度**：基于信息几何学的数学相似度度量
- **零 LLM 模式（Mode A）**：无需外部 API，纯本地计算
- **EU AI Act 合规**：内置信任评分和审计追踪
- **多 IDE 集成**：支持 Claude Desktop、Cursor、Windsurf 等 17+ AI 工具
资料来源：[README.md](https://github.com/qualixar/superlocalmemory/blob/main/README.md)
## 核心架构
SuperLocalMemory 采用分层架构设计，包含七个核心层次，从数据存储到用户界面的完整技术栈。
```mermaid
graph TD
subgraph "用户访问层"
A[CLI 命令行] --> B[REST API]
B --> C[Web UI]
C --> D[MCP 协议]
end
subgraph "服务层"
E[Unified Daemon] --> F[路由引擎]
F --> G[聊天路由]
G --> H[记忆路由]
end
subgraph "核心引擎"
I[Memory Engine V3] --> J[4-Channel Retrieval]
J --> K[Fisher-Rao Similarity]
K --> L[Trust Scoring]
end
subgraph "存储层"
M[SQLite Database] --> N[记忆表]
N --> O[配置文件]
end
D --> E
E --> I
I --> M
```
### 架构层级说明
| 层级 | 组件 | 功能描述 |
|------|------|----------|
| 用户访问层 | CLI、REST API、Web UI、MCP | 提供多种访问方式 |
| 服务层 | Unified Daemon、路由引擎 | 请求处理与业务逻辑 |
| 核心引擎 | Memory Engine、4-Channel Retrieval、Trust Scoring | 记忆检索与评分 |
| 存储层 | SQLite | 本地持久化存储 |
资料来源：[src/superlocalmemory/server/api.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/api.py)
## 两种运行模式
SuperLocalMemory 支持两种运行模式，适用于不同的使用场景和隐私需求。
### Mode A：零 LLM 模式
纯本地计算模式，不依赖任何外部 LLM API。所有记忆检索基于 Fisher-Rao 相似度和四通道检索算法实现。
**适用场景**：
- 高度敏感的数据环境
- 无网络连接的离线环境
- 追求最快响应速度的场景
```python
# Mode A 配置示例
config = SLMConfig.for_mode("A")
```
### Mode B：LLM 增强模式
利用外部 LLM（如 Ollama、OpenAI 兼容 API）增强记忆理解能力。支持可配置的 API 端点和自定义模型。
**适用场景**：
- 需要更深层语义理解的场景
- 复杂对话上下文处理
- 非英语语言的语义检索
```python
# Mode B 配置示例
config = SLMConfig.for_mode("B", provider="ollama", model="llama3")
```
资料来源：[src/superlocalmemory/core/config.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/config.py)
## 安装与快速开始
### 系统要求
| 要求 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Python | 3.9+ | 3.12+ |
| Node.js | 16.0+ | 20.0+ |
| 内存 | 4GB | 8GB+ |
| 磁盘空间 | 500MB | 2GB+ |
### 安装方式
**通过 npm 全局安装（推荐）**：
```bash
npm install -g superlocalmemory
```
**通过 pip 安装**：
```bash
pip install superlocalmemory
```
安装完成后，运行 `slm setup` 启动交互式配置向导，系统会自动下载嵌入模型并完成初始配置。
资料来源：[package.json](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
## 命令行接口
SuperLocalMemory 提供完整的命令行工具，支持所有核心操作。
| 命令 | 功能 | 示例 |
|------|------|------|
| `slm remember` | 存储新记忆 | `slm remember 今天完成了API设计` |
| `slm recall` | 语义检索记忆 | `slm recall 项目进度` |
| `slm forget` | 删除匹配记忆 | `slm forget 旧项目` |
| `slm delete` | 按 ID 删除记忆 | `slm delete ` |
| `slm update` | 更新记忆内容 | `slm update ` |
| `slm list-recent` | 列出最近记忆 | `slm list-recent --limit 20` |
| `slm status` | 查看系统状态 | `slm status` |
| `slm switch-profile` | 切换工作环境 | `slm switch-profile work` |
### recall 命令选项
```bash
slm recall "查询内容" [选项]
```
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--limit` | 最大返回结果数 | 10 |
| `--json` | 输出结构化 JSON | false |
| `--fast` | 跳过第五通道加速检索 | false |
资料来源：[src/superlocalmemory/cli/main.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
## MCP 集成
SuperLocalMemory 实现了 MCP（Model Context Protocol）协议，可与多种 AI 开发工具无缝集成。
### 支持的 IDE
- Claude Desktop
- Cursor
- Windsurf
- Continue.dev
- ChatGPT
- Perplexity
- Zed
- Cody
- Aider
- OpenCode
- Antigravity
### MCP 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `slm-remember` | 存储新的记忆条目 |
| `slm-recall` | 执行语义检索 |
| `slm-list-recent` | 获取最近的记忆列表 |
| `slm-status` | 查看系统状态和统计 |
| `slm-build-graph` | 生成知识图谱 |
| `slm-switch-profile` | 切换当前配置文件 |
资料来源：[wiki-content/v2-archive/README.md](https://github.com/qualixar/superlocalmemory/blob/main/wiki-content/v2-archive/README.md)
## LangChain 和 LlamaIndex 集成
SuperLocalMemory 提供与主流 AI 框架的原生集成，扩展其使用场景。
### LangChain 集成
通过 `langchain-superlocalmemory` 包，将 SuperLocalMemory 作为 LangChain 的聊天历史存储后端。
```python
from langchain_core.messages import AIMessage, HumanMessage
from langchain_superlocalmemory import SuperLocalMemoryChatMessageHistory
history = SuperLocalMemoryChatMessageHistory(session_id="my-session")
history.add_messages([
HumanMessage(content="What is SuperLocalMemory?"),
AIMessage(content="It's a local-first memory system."),
])
```
**特性**：
- 完全本地存储，数据不离开本机
- 会话隔离，每个 session_id 独立存储
- 完整兼容 LangChain 接口
- 消息持久化，重启后数据保留
资料来源：[ide/integrations/langchain/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/langchain/README.md)
### LlamaIndex 集成
通过 `llama-index-storage-chat-store-superlocalmemory` 包，LlamaIndex 应用可使用 SuperLocalMemory 作为聊天存储。
```python
from llama_index.core.memory import ChatMemoryBuffer
from llama_index.storage.chat_store.superlocalmemory import SuperLocalMemoryChatStore
chat_store = SuperLocalMemoryChatStore()
memory = ChatMemoryBuffer.from_defaults(
chat_store=chat_store,
chat_store_key="user-123",
token_limit=3000,
)
```
资料来源：[ide/integrations/llamaindex/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/llamaindex/README.md)
## Web UI 和 API 服务
SuperLocalMemory 提供基于 FastAPI 的 Web 服务，支持 REST API 和 WebSocket 实时通信。
### 服务启动
```bash
slm serve
```
服务默认在 `http://localhost:8765` 运行，支持以下端点：
| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/chat` | POST | 聊天对话（流式响应） |
| `/api/memories` | GET/POST | 记忆 CRUD 操作 |
| `/api/recall` | POST | 语义检索 |
| `/api/stats` | GET | 系统统计信息 |
| `/api/profiles` | GET | 配置文件管理 |
### 聊天 SSE 接口
```mermaid
sequenceDiagram
participant Client
participant API
participant MemoryEngine
participant LLM
Client->>API: POST /api/chat (query + memories)
API->>MemoryEngine: 4-Channel Retrieval
MemoryEngine-->>API: 检索结果 + Trust Score
API->>LLM: 上下文 + 查询
LLM-->>API: Stream Tokens
API-->>Client: SSE Events
```
资料来源：[src/superlocalmemory/server/routes/chat.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/routes/chat.py)
## 数据目录与环境变量
SuperLocalMemory 使用本地文件系统存储所有数据，默认位置为 `~/.superlocalmemory/`。
### 目录结构
```
~/.superlocalmemory/
├── memory.db # 主数据库（SQLite）
├── config.yaml # 配置文件
├── .setup-complete # 设置完成标记
└── ui/ # Web UI 资源
```
### 环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SLM_DATA_DIR` | 数据目录位置 | `~/.superlocalmemory` |
| `SLM_HOST` | 服务绑定地址 | `127.0.0.1` |
| `SL_MEMORY_PATH` | 内存路径 | 同 `SLM_DATA_DIR` |
资料来源：[src/superlocalmemory/cli/setup_wizard.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
## 常见问题与已知问题
### Docker/Linux 环境问题
在 Docker 或 Linux 环境中运行时，部分用户报告认知整合和追踪问题。确保容器内正确配置了 Python 3.9+ 和必要的系统依赖。
相关 Issue：[#26](https://github.com/qualixar/superlocalmemory/issues/26)
### SLM_HOST 功能请求
当前版本中，守护进程和 mesh broker 将绑定地址硬编码为 `127.0.0.1`。对于需要在多机器集群（如 WireGuard mesh）环境中使用的用户，建议通过环境变量配置自定义主机地址。
相关 Issue：[#23](https://github.com/qualixar/superlocalmemory/issues/23)
### 非英语语言支持
Mode B 支持配置本地嵌入端点（如 OpenAI 兼容 API），以解锁非英语语言的语义检索能力。配置方法：
```python
config = SLMConfig.for_mode(
"B",
embedding_endpoint="http://localhost:11434/api/embeddings"
)
```
相关 Issue：[#16](https://github.com/qualixar/superlocalmemory/issues/16)
## 版本历史与特性演进
| 版本 | 发布日期 | 主要特性 |
|------|----------|----------|
| v3.4.58 | 最新 | V3 引擎、信任系统、学习系统 |
| v2.8.0 | 2024 | 记忆生命周期管理、行为学习、企业合规 |
| v2.7.0 | 2024 | 自适应学习、个性化排名 |
| v2.6.0 | 2024 | 安全加固、配置文件隔离 |
资料来源：[package.json](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
## 安全与合规
SuperLocalMemory V2.6.0 及更高版本包含全面的安全加固：
- **配置文件隔离**：所有查询端点实现记忆隔离，防止跨配置泄露
- **信任评分系统**：基于 Fisher-Rao 信息几何学的可信度评估
- **不可变审计日志**：完整的访问和操作审计追踪
- **EU AI Act 合规**：满足欧盟人工智能法案要求
资料来源：[src/superlocalmemory/server/ui.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
## 技术支持与参与
- **问题反馈**：[GitHub Issues](https://github.com/qualixar/superlocalmemory/issues)
- **功能请求**：[GitHub Discussions](https://github.com/qualixar/superlocalmemory/discussions)
- **官方网站**：[superlocalmemory.com](https://superlocalmemory.com)
- **开发者**：[Varun Pratap Bhardwaj](https://github.com/varun369)
## 另请参阅
- [Universal Architecture（通用架构）](Universal-Architecture) — 七层架构详解
- [MCP Integration（MCP 集成）](MCP-Integration) — 完整的 MCP 设置指南
- [Universal Skills（通用技能）](Universal-Skills) — 六种通用命令文档
- [Installation（安装指南）](Installation) — 详细安装说明
- [FAQ（常见问题）](FAQ) — 常见问题解答
---
## 快速入门
### 相关页面
相关主题：[首页](#page-home), [三种运行模式详解](#page-modes), [CLI 参考手册](#page-cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/cli/setup_wizard.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
- [src/superlocalmemory/cli/post_install.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/post_install.py)
- [src/superlocalmemory/server/api.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/api.py)
- [src/superlocalmemory/server/ui.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
- [src/superlocalmemory/server/unified_daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
- [package.json](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
- [ide/integrations/langchain/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/langchain/README.md)
- [ide/integrations/llamaindex/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/llamaindex/README.md)
# 快速入门
SuperLocalMemory 是一款本地优先的 AI 记忆系统，采用信息几何学方法实现记忆存储与检索。本页面将引导您完成从安装到首次使用的完整流程，帮助您在数分钟内启动并运行 SuperLocalMemory。
---
## 系统要求
在开始安装之前，请确保您的环境满足以下要求：
| 要求项 | 最低版本 | 推荐版本 | 说明 |
|--------|----------|----------|------|
| Python | 3.9+ | 3.10+ | 核心运行时环境 |
| Node.js | 18.0.0 | 20.x LTS | NPM 包管理器 |
| npm | 9.0.0 | 最新版 | 用于全局安装 CLI |
| 磁盘空间 | 500MB | 2GB+ | 包含嵌入模型 |
| 操作系统 | macOS/Linux/Windows | macOS/Linux | 全平台支持 |
**支持的操作系统：**
- macOS (darwin)
- Linux (linux)
- Windows (win32)
资料来源：[package.json:35-38](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
---
## 安装方式
SuperLocalMemory 提供两种安装方式，您可以根据偏好选择：
### 方式一：NPM 全局安装（推荐）
```bash
npm install -g superlocalmemory
```
安装完成后，`slm` 命令将全局可用：
```bash
slm --version
```
资料来源：[package.json:28-33](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
### 方式二：pip 安装
```bash
pip install superlocalmemory
```
两种方式共享相同的底层存储和数据目录，可以混合使用。
---
## 安装后配置流程
安装完成后，系统将自动触发安装后脚本。根据您是否是首次安装，流程会有所不同：
```mermaid
graph TD
A[npm install -g superlocalmemory] --> B{检测到 V2 版本?}
B -->|是| C[显示升级提示]
B -->|否| D{首次安装?}
D -->|是| E[运行设置向导]
D -->|否| F[检查 .setup-complete]
C --> G[执行数据迁移]
E --> H[下载嵌入模型]
H --> I[配置 LLM 模式]
I --> J[启动服务]
F -->|已完成| J
F -->|未完成| E
G --> J
```
资料来源：[src/superlocalmemory/cli/post_install.py:26-40](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/post_install.py)
---
## 首次设置向导
首次运行任何 `slm` 命令时，系统会自动启动交互式设置向导。您也可以手动触发：
```bash
slm setup
```
### 设置向导流程
设置向导负责以下核心任务：
| 步骤 | 功能 | 说明 |
|------|------|------|
| 1 | 环境检测 | 检测操作系统、Python、Node.js 版本 |
| 2 | 模型下载 | 下载 nomic-embed-text-v1.5 嵌入模型 |
| 3 | Reranker 模型 | 下载 ms-marco-MiniLM-L-12-v2 重排模型 |
| 4 | 模式选择 | 选择 Mode A（本地）或 Mode B（云端） |
| 5 | LLM 配置 | 配置 Ollama 或 OpenAI 兼容 API |
| 6 | 验证安装 | 运行健康检查确认配置正确 |
资料来源：[src/superlocalmemory/cli/setup_wizard.py:35-50](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
### 默认嵌入模型配置
```python
_EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5"
_RERANKER_MODEL = "cross-encoder/ms-marco-MiniLM-L-12-v2"
```
资料来源：[src/superlocalmemory/cli/setup_wizard.py:38-39](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
### 交互式检测
设置向导会检测运行环境是否为交互式终端：
```python
def is_interactive() -> bool:
"""True if running in a terminal (not CI, not piped, not MCP)."""
if os.environ.get("CI"):
return False
if os.environ.get("SLM_NON_INTERACTIVE"):
return False
return sys.stdin.isatty() and sys.stdout.isatty()
```
资料来源：[src/superlocalmemory/cli/setup_wizard.py:52-58](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
**非交互环境处理：**
- CI 环境：自动跳过交互提示
- MCP 调用：静默跳过
- 管道输入：使用默认值
---
## 基础命令
安装并配置完成后，您可以使用以下核心命令：
### 记忆存储
```bash
# 存储新记忆
slm remember 今天学会了 Python 的异步编程
# 查看最近记忆
slm list-recent
# 搜索记忆
slm recall "异步编程"
```
### 状态检查
```bash
# 检查系统状态
slm status
# 运行诊断
slm doctor
```
### 配置管理
```bash
# 查看当前配置
slm config
# 切换配置文件
slm switch-profile
```
---
## 诊断命令详解
`slm doctor` 命令用于验证系统配置，检测常见问题：
```mermaid
graph LR
A[slm doctor] --> B[检测 Python 版本]
B --> C[检测 Node.js 版本]
C --> D[检查数据库连接]
D --> E[验证嵌入模型]
E --> F{检查 LLM 提供商}
F -->|Ollama| G[测试 Ollama 连接]
F -->|OpenAI| H[测试 API 密钥]
G --> I[生成诊断报告]
H --> I
```
**常见诊断问题及解决方案：**
| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| 数据库连接失败 | 权限不足 | 检查 `~/.superlocalmemory/` 目录权限 |
| 嵌入模型缺失 | 首次安装未完成 | 运行 `slm setup` |
| Ollama 连接失败 | 服务未启动 | 运行 `ollama serve` |
| API 密钥无效 | Mode B 配置错误 | 检查 `SLM_CONFIG` 环境变量 |
---
## 数据目录
SuperLocalMemory 使用以下默认数据目录：
| 环境变量 | 默认路径 | 用途 |
|----------|----------|------|
| `SL_MEMORY_PATH` | `~/.superlocalmemory/` | 主数据目录 |
| `SLM_DATA_DIR` | — | 可自定义数据目录 |
| 数据库文件 | `memory.db` | SQLite 记忆存储 |
```bash
# 自定义数据目录
export SLM_DATA_DIR=/path/to/custom/directory
# 或使用环境变量
export SL_MEMORY_PATH=~/.my-custom-sl
```
> **注意**：虽然 `SLM_DATA_DIR` 在文档中有所提及，但实际使用中推荐使用 `SL_MEMORY_PATH` 环境变量。
资料来源：[src/superlocalmemory/cli/setup_wizard.py:30](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
---
## 启动服务
SuperLocalMemory 提供多种服务启动方式：
### API 服务器
```bash
slm serve
```
服务器默认配置：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 主机地址 | 127.0.0.1 | 本地绑定 |
| API 端口 | 8765 | REST API 端点 |
| UI 端口 | 8417 | Web 界面端口 |
| CORS 来源 | localhost:8765, localhost:8417 | 允许的前端域名 |
```python
allow_origins=[
"http://localhost:8765", "http://127.0.0.1:8765",
"http://localhost:8417", "http://127.0.0.1:8417",
]
```
资料来源：[src/superlocalmemory/server/ui.py:28-34](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
### 守护进程
```bash
slm daemon
```
守护进程在后台持续运行，支持：
- 记忆自动存储
- 上下文预热
- 生命周期管理
- 行为学习
```python
# 升级检测横幅
_want_write_marker = _prev != _slm_version
if _want_write_marker:
if _prev is None:
logger.info(
"[slm] first boot on v%s — run `slm status` to see your "
"memory overview. Changelog: "
"https://github.com/qualixar/superlocalmemory/blob/main/CHANGELOG.md",
_slm_version,
)
```
资料来源：[src/superlocalmemory/server/unified_daemon.py:1-30](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
---
## 与 LangChain 集成
如果您使用 LangChain 构建 AI 应用，可以将 SuperLocalMemory 作为聊天历史存储：
```python
from langchain_core.messages import AIMessage, HumanMessage
from langchain_superlocalmemory import SuperLocalMemoryChatMessageHistory
# 创建会话历史
history = SuperLocalMemoryChatMessageHistory(session_id="my-session")
# 添加消息
history.add_messages([
HumanMessage(content="Hello!"),
AIMessage(content="Hi, how can I help you?"),
])
# 获取消息
for msg in history.messages:
print(f"{msg.type}: {msg.content}")
# 清空会话
history.clear()
```
**特性：**
- 本地存储：所有数据保存在 `~/.superlocalmemory/memory.db`
- 会话隔离：不同 `session_id` 完全独立
- 元数据保留：`additional_kwargs` 完整序列化
资料来源：[ide/integrations/langchain/README.md:1-60](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/langchain/README.md)
---
## 与 LlamaIndex 集成
LlamaIndex 用户可以使用 SuperLocalMemory 作为聊天存储后端：
```python
from llama_index.core.memory import ChatMemoryBuffer
from llama_index.core.base.llms.types import ChatMessage, MessageRole
from llama_index.storage.chat_store.superlocalmemory import SuperLocalMemoryChatStore
# 创建聊天存储
chat_store = SuperLocalMemoryChatStore()
# 与 ChatMemoryBuffer 结合使用
memory = ChatMemoryBuffer.from_defaults(
chat_store=chat_store,
chat_store_key="user-123",
token_limit=3000,
)
# 添加消息
chat_store.add_message("session-1", ChatMessage(role=MessageRole.USER, content="Hello!"))
```
**存储格式：**
- 内容：JSON 序列化的 `{role, content, additional_kwargs}`
- 标签：`llamaindex:chat:` 用于会话隔离
- 项目：`llamaindex` 便于识别
- 重要性：3（较低，避免聊天历史干扰搜索结果）
资料来源：[ide/integrations/llamaindex/README.md:1-80](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/llamaindex/README.md)
---
## 常见问题
### 安装后命令无响应
如果 `slm remember xxx` 命令长时间无响应，可能是模型下载未完成。请尝试：
```bash
slm doctor
```
此问题已在 **v3.3.19** 版本中修复。资料来源：[GitHub Issue #11](https://github.com/qualixar/superlocalmemory/issues/11)
### Docker/Linux 环境问题
在 Docker 或 Linux 环境中运行时，确保：
1. Python 版本 >= 3.9
2. Ollama 服务正确配置
3. 网络端口未被占用
4. 数据目录权限正确
详细诊断请参考：[GitHub Issue #26](https://github.com/qualixar/superlocalmemory/issues/26)
### 网络绑定限制
当前版本中，API 服务器和守护进程默认绑定到 `127.0.0.1`。如需远程访问，可以：
1. 使用 `slm-mesh` 建立 WireGuard mesh 网络
2. 配置反向代理
3. 等待官方 SLM_HOST 功能支持
资料来源：[GitHub Issue #23](https://github.com/qualixar/superlocalmemory/issues/23)
---
## 下一步
完成快速入门后，您可以深入探索以下内容：
| 主题 | 说明 |
|------|------|
| [通用架构](./Universal-Architecture) | 了解 SuperLocalMemory 的 7 层架构设计 |
| [MCP 集成](./MCP-Integration) | 将 SuperLocalMemory 集成到 11+ IDE |
| [通用技能](./Universal-Skills) | 使用 6 种通用命令技能 |
| [安装指南](./Installation) | 详细的安装和环境配置 |
| [常见问题](./FAQ) | 更多问题解答 |
---
## 相关链接
- **项目主页**：https://github.com/qualixar/superlocalmemory
- **官方文档**：https://superlocalmemory.com
- **问题反馈**：https://github.com/qualixar/superlocalmemory/issues
- **版本更新**：https://github.com/qualixar/superlocalmemory/blob/main/CHANGELOG.md
**维护者**：Varun Pratap Bhardwaj
**许可证**：AGPL-3.0-or-later
---
## V3 架构
### 相关页面
相关主题：[首页](#page-home), [检索管道](#page-retrieval-pipeline), [记忆生命周期](#page-memory-lifecycle)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/ARCHITECTURE.md](https://github.com/qualixar/superlocalmemory/blob/main/docs/ARCHITECTURE.md)
- [src/superlocalmemory/core/engine.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/engine.py)
- [src/superlocalmemory/core/backend_orchestrator.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/backend_orchestrator.py)
- [src/superlocalmemory/retrieval/engine.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/engine.py)
- [src/superlocalmemory/retrieval/semantic_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/semantic_channel.py)
- [src/superlocalmemory/retrieval/bm25_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/bm25_channel.py)
- [src/superlocalmemory/retrieval/entity_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/entity_channel.py)
- [src/superlocalmemory/retrieval/temporal_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/temporal_channel.py)
- [src/superlocalmemory/retrieval/hopfield_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/hopfield_channel.py)
- [src/superlocalmemory/retrieval/fusion.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/fusion.py)
- [src/superlocalmemory/retrieval/reranker.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/reranker.py)
- [src/superlocalmemory/math/fisher.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/math/fisher.py)
# V3 架构
SuperLocalMemory V3 是一个基于信息几何学的 AI 代理记忆系统，通过数学保证实现高精度检索。本文档详细阐述 V3 的系统架构、核心组件以及检索管道的实现原理。
## 概述
V3 架构的核心设计理念是**零 LLM 推理的本地模式（Zero-LLM Mode）**，同时支持 EU AI Act 合规性要求。系统采用四通道检索机制，结合 Fisher-Rao 相似度进行信息几何学度量，实现精确的记忆召回。
资料来源：[docs/ARCHITECTURE.md:1-50]()
### 核心特性
| 特性 | 描述 |
|------|------|
| 四通道检索 | 语义、BM25、实体、时间四维并行检索 |
| Fisher-Rao 相似度 | 基于信息几何学的概率分布相似度度量 |
| 零 LLM 模式 | 无需 LLM 推理，纯本地模式运行 |
| EU AI Act 合规 | 完整访问控制、不可变审计追踪 |
| 多模式支持 | Mode A（本地 Ollama）、Mode B（云端 API） |
## 系统架构图
```mermaid
graph TD
subgraph "客户端层"
CLI[CLI 命令行]
MCP[MCP 协议]
REST[REST API]
WS[WebSocket]
end
subgraph "服务层"
Daemon[统一守护进程
unified_daemon.py]
API[FastAPI 服务器
api.py]
UI[UI 服务器
ui.py]
end
subgraph "核心引擎层"
Engine[MemoryEngine
core/engine.py]
Orchestrator[BackendOrchestrator
backend_orchestrator.py]
end
subgraph "检索管道层"
Semantic[语义通道]
BM25[BM25 通道]
Entity[实体通道]
Temporal[时间通道]
Hopfield[Hopfield 通道]
Fusion[融合模块]
Reranker[重排器]
end
subgraph "数学模块层"
Fisher[Fisher-Rao 距离
math/fisher.py]
Riemannian[黎曼几何工具]
end
subgraph "存储层"
SQLite[(SQLite
memory.db)]
Cache[上下文缓存
ContextCache]
end
CLI --> Daemon
MCP --> Daemon
REST --> API
WS --> API
UI --> API
Daemon --> Engine
API --> Engine
Engine --> Orchestrator
Orchestrator --> Semantic
Orchestrator --> BM25
Orchestrator --> Entity
Orchestrator --> Temporal
Orchestrator --> Hopfield
Semantic --> Fusion
BM25 --> Fusion
Entity --> Fusion
Temporal --> Fusion
Hopfield --> Fusion
Fusion --> Reranker
Reranker --> Engine
Engine --> SQLite
Engine --> Cache
Fusion --> Fisher
```
## 核心引擎
### MemoryEngine
MemoryEngine 是 V3 的中央协调器，负责处理所有记忆操作请求。它协调检索管道、数学计算模块和存储后端之间的交互。
资料来源：[src/superlocalmemory/core/engine.py:1-100]()
```python
class MemoryEngine:
"""V3 MemoryEngine - 中央记忆处理引擎"""
def __init__(self, config: SLMConfig):
self.config = config
self.orchestrator = BackendOrchestrator(config)
self._initializeRetrievalPipeline()
async def remember(self, content: str, metadata: dict) -> str:
"""存储新记忆"""
fact_id = await self.orchestrator.store(content, metadata)
return fact_id
async def recall(self, query: str, context: dict) -> list[MemoryEntry]:
"""检索相关记忆"""
results = await self.orchestrator.retrieve(query, context)
return results
```
### BackendOrchestrator
BackendOrchestrator 负责管理多个后端服务的协调工作，包括 LLM 后端、嵌入后端和存储后端的生命周期。
资料来源：[src/superlocalmemory/core/backend_orchestrator.py:1-80]()
## 四通道检索管道
V3 采用四通道并行检索架构，每个通道从不同维度评估记忆相关性，最终通过融合模块整合结果。
资料来源：[src/superlocalmemory/retrieval/engine.py:1-60]()
### 通道详解
| 通道 | 文件 | 功能 | 适用场景 |
|------|------|------|----------|
| 语义通道 | `retrieval/semantic_channel.py` | 向量嵌入相似度检索 | 概念匹配、语义理解 |
| BM25 通道 | `retrieval/bm25_channel.py` | 词项频率-逆文档频率 | 关键词精确匹配 |
| 实体通道 | `retrieval/entity_channel.py` | 命名实体识别与链接 | 人物、地点、机构关联 |
| 时间通道 | `retrieval/temporal_channel.py` | 时间衰减与时序分析 | 最近事件、时间敏感查询 |
| Hopfield 通道 | `retrieval/hopfield_channel.py` | 联想记忆模式匹配 | 模式补全、关联推理 |
### 检索流程图
```mermaid
sequenceDiagram
participant Client as 客户端
participant Engine as MemoryEngine
participant Orch as BackendOrchestrator
participant Semantic as 语义通道
participant BM25 as BM25通道
participant Entity as 实体通道
participant Temporal as 时间通道
participant Fusion as 融合模块
participant Reranker as 重排器
Client->>Engine: recall(query, context)
Engine->>Orch: retrieve(query, context)
Orch->>Semantic: search(query)
Orch->>BM25: search(query)
Orch->>Entity: search(query)
Orch->>Temporal: search(query)
Semantic-->>Fusion: scores[]
BM25-->>Fusion: scores[]
Entity-->>Fusion: scores[]
Temporal-->>Fusion: scores[]
Fusion->>Fusion: 归一化 + 加权融合
Fusion->>Reranker: candidate_facts
alt 使用重排器
Reranker->>Reranker: cross-encoder 重排
end
Reranker-->>Engine: ranked_results
Engine-->>Client: top_k memories
```
## Fisher-Rao 相似度
Fisher-Rao 距离是 V3 的核心数学基础，用于度量概率分布之间的信息几何距离。相比传统的余弦相似度或欧氏距离，Fisher-Rao 距离具有以下优势：
- **参数无关性**：对参数化方式不变
- **统计一致性**：与最大似然估计理论一致
- **几何不变性**：在概率分布流形上具有不变性
资料来源：[src/superlocalmemory/math/fisher.py:1-100]()
### 数学原理
给定两个概率分布 $p$ 和 $q$，Fisher-Rao 距离定义为：
$$d_{FR}(p, q) = \arccos\left( \int \sqrt{p(x) q(x)} dx \right)$$
在实际实现中，系统使用嵌入向量构造经验概率分布，然后计算黎曼流形上的测地线距离。
## 融合模块
Fusion 模块负责整合四个检索通道的结果，生成统一的候选列表。
资料来源：[src/superlocalmemory/retrieval/fusion.py:1-80]()
### 融合策略
| 策略 | 描述 | 适用场景 |
|------|------|----------|
| RRF (Reciprocal Rank Fusion) | 基于排名的倒数融合 | 多通道结果排序 |
| 分数加权平均 | 归一化分数加权求和 | 通道重要性明确 |
| 置信度融合 | 基于 Fisher-Rao 置信区间 | 高精度需求 |
## 重排器
重排器使用 cross-encoder 模型对候选记忆进行二次排序，提高最终结果的相关性。
资料来源：[src/superlocalmemory/retrieval/reranker.py:1-60]()
```python
class Reranker:
"""Cross-encoder 重排器"""
def __init__(self, model_name: str = "cross-encoder/ms-marco-MiniLM-L-12-v2"):
self.model = CrossEncoder(model_name)
async def rerank(self, query: str, candidates: list[dict]) -> list[dict]:
"""对候选记忆进行重排"""
pairs = [(query, candidate["content"]) for candidate in candidates]
scores = self.model.predict(pairs)
ranked = sorted(
zip(candidates, scores),
key=lambda x: x[1],
reverse=True
)
return [c for c, _ in ranked]
```
## 服务架构
### 统一守护进程
`unified_daemon.py` 是 V3 的核心后台服务，负责启动所有子服务和协调版本迁移。
资料来源：[src/superlocalmemory/server/unified_daemon.py:1-150]()
```mermaid
graph LR
A[启动] --> B{检测 V2 安装}
B -->|是| C[运行迁移]
B -->|否| D[检查版本标记}
C --> E[初始化 V3 数据库]
D -->|首次启动| F[显示欢迎横幅]
D -->|升级| G[显示升级信息]
E --> H[启动 FastAPI 服务]
F --> H
G --> H
H --> I[注册路由]
I --> J[监听请求]
```
### API 服务器
FastAPI 服务器提供 REST API 接口，支持记忆的增删改查操作。
资料来源：[src/superlocalmemory/server/api.py:1-100]()
| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/search` | POST | 语义搜索记忆 |
| `/api/memories` | GET | 获取记忆列表 |
| `/api/memories` | POST | 创建新记忆 |
| `/api/memories/{id}` | GET | 获取单条记忆 |
| `/api/memories/{id}` | DELETE | 删除记忆 |
| `/api/stats` | GET | 获取统计信息 |
| `/internal/prewarm` | POST | 预热上下文缓存 |
### UI 服务器
UI 服务器提供 Web 界面访问，运行在独立端口上。
资料来源：[src/superlocalmemory/server/ui.py:1-120]()
- **默认端口**: 8765 或 8417
- **CORS 配置**: 仅允许 localhost 访问
- **中间件**: GZip 压缩、安全头、CORS
## 配置与模式
### 运行模式
| 模式 | 描述 | LLM 后端 |
|------|------|----------|
| Mode A | 本地 Ollama | Ollama (本地) |
| Mode B | 云端 API | OpenAI 兼容 API |
### 环境变量
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `SLM_DATA_DIR` | `~/.superlocalmemory` | 数据目录 |
| `SLM_HOST` | `127.0.0.1` | 绑定地址 |
| `SL_MEMORY_PATH` | `~/.superlocalmemory` | 内存路径 |
> ⚠️ **社区问题**: Issue #10 指出 `SLM_DATA_DIR` 虽然有文档说明但实际未被使用，Issue #23 报告 `SLM_HOST` 硬编码为 `127.0.0.1`，在多机器部署场景下存在限制。
## 安装向导
首次启动时，系统会运行交互式安装向导，下载必要的嵌入模型。
资料来源：[src/superlocalmemory/cli/setup_wizard.py:1-100]()
```bash
# 默认嵌入模型
_EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5"
# 默认重排模型
_RERANKER_MODEL = "cross-encoder/ms-marco-MiniLM-L-12-v2"
```
安装流程：
1. 检测交互式终端环境
2. 检查 Ollama 是否可用（Mode A）
3. 下载并缓存嵌入模型
4. 初始化 SQLite 数据库
5. 写入 `.setup-complete` 标记
## 常见问题与故障排除
### Issue #11: `slm remember` 无响应
**问题描述**: 命令执行后长时间等待无输出。
**解决方案**: 此问题已在 **v3.3.19** 中修复，请升级到最新版本。
### Issue #26: Linux/Docker 环境问题
**问题描述**: 在 Ubuntu/Debian Docker 容器中运行时出现认知整合和追踪问题。
**可能原因**:
- 容器内资源限制
- SQLite 文件权限问题
- Ollama 服务未正确配置
### Issue #9: Mode B 的 `api_key` 被忽略
**问题描述**: 配置的 `api_key` 在 Mode B 下被静默丢弃。
**文件位置**: `src/superlocalmemory/core/config.py` 的 `SLMConfig.for_mode()` 方法
**影响**: `LLMBackbone.is_available()` 对非 Ollama 提供商返回 `False`
## 扩展集成
### MCP 协议支持
V3 通过 MCP（Model Context Protocol）提供标准化的工具和资源接口。
### LangChain 集成
提供 `langchain-superlocalmemory` 包，支持 LangChain 的 `BaseChatMessageHistory` 接口。
### LlamaIndex 集成
提供 LlamaIndex 的 `BaseChatStore` 实现，所有聊天历史存储在本地 SQLite 数据库中。
## 版本信息
| 版本 | 发布日期 | 主要特性 |
|------|----------|----------|
| v3.4.58 | 2026-02 | 最新稳定版 |
| v3.3.19 | 2025 | 修复 remember 无响应问题 |
| v2.8.0 | 2025 | 记忆生命周期、行为学习、企业合规 |
| v2.7.0 | 2025 | 自适应学习、个性化排序 |
## 相关文档
- [安装指南](./Installation)
- [MCP 集成](./MCP-Integration)
- [通用技能](./Universal-Skills)
- [常见问题](./FAQ)
- [CHANGELOG](https://github.com/qualixar/superlocalmemory/blob/main/CHANGELOG.md)
---
## 三种运行模式详解
### 相关页面
相关主题：[V3 架构](#page-architecture), [配置参考](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/core/modes.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/modes.py)
- [src/superlocalmemory/core/config.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/config.py)
- [src/superlocalmemory/llm/backbone.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/llm/backbone.py)
- [src/superlocalmemory/compliance/eu_ai_act.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/compliance/eu_ai_act.py)
- [src/superlocalmemory/cli/main.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
- [src/superlocalmemory/server/unified_daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
# 三种运行模式详解
SuperLocalMemory（SLM）提供了灵活的三种运行模式，允许用户根据不同的使用场景和硬件条件选择最适合的配置。本文详细介绍每种模式的工作原理、配置方法以及适用场景。
## 模式概述
SuperLocalMemory 的三种运行模式是系统的核心架构设计，它们决定了记忆系统的检索方式、依赖组件和性能特征：
| 模式 | 名称 | LLM依赖 | 嵌入模型 | 典型延迟 | 适用场景 |
|------|------|---------|----------|----------|----------|
| **Mode A** | 零LLM模式 | ❌ 无需 | 本地Nomic | <100ms | 快速响应、离线环境、低配硬件 |
| **Mode B** | 增强模式 | ✅ Ollama/API | 本地/远程 | 200-500ms | 高精度检索、多语言支持 |
| **Mode C** | 云端模式 | ✅ OpenAI兼容 | 远程API | 500ms+ | 无本地GPU、需要云端算力 |
资料来源：[src/superlocalmemory/core/modes.py:1-50]()
## Mode A：零LLM模式
### 工作原理
Mode A 是 SuperLocalMemory 的核心创新之一，实现了完全本地化的记忆检索。在该模式下，系统不依赖任何大型语言模型（LLM），而是通过纯数学方法实现语义搜索：
- **Fisher-Rao 度量**：利用信息几何理论计算记忆间的相似度
- **扩散激活算法**：基于图结构的记忆传播机制
- **四通道检索**：语义、词法、时间、结构四个维度并行检索
资料来源：[src/superlocalmemory/compliance/eu_ai_act.py:1-30]()
### 核心优势
```
graph TD
A[用户查询] --> B{模式检测}
B -->|Mode A| C[Fisher-Rao度量]
B -->|Mode B| D[LLM重排序]
B -->|Mode C| E[云端API]
C --> F[四通道并行检索]
D --> G[本地嵌入]
E --> H[远程嵌入]
F --> I[结果融合]
G --> I
H --> I
I --> J[记忆输出]
```
Mode A 的主要优势包括：
1. **零API成本**：不产生任何外部服务费用
2. **隐私保证**：所有数据处理均在本地完成
3. **快速响应**：端到端延迟通常低于100毫秒
4. **离线可用**：不依赖网络连接
资料来源：[src/superlocalmemory/llm/backbone.py:50-80]()
### 配置方法
```bash
# 切换到 Mode A（零LLM模式）
slm mode a
# 验证当前模式
slm status
```
配置文件位于 `~/.superlocalmemory/config.yaml`：
```yaml
mode: a
embedding:
provider: local
model: nomic-ai/nomic-embed-text-v1.5
```
资料来源：[src/superlocalmemory/core/config.py:100-150]()
## Mode B：增强模式
### 工作原理
Mode B 通过集成本地运行的 LLM（通常是 Ollama）来增强检索精度。该模式下，系统使用本地嵌入模型生成向量表示，并通过 LLM 进行结果重排序和上下文扩展：
- **本地嵌入**：使用 Nomic 或其他本地嵌入模型
- **Ollama 集成**：通过 Ollama API 调用本地 LLM
- **API Key 支持**：支持 OpenAI 兼容的 API 端点
资料来源：[src/superlocalmemory/core/config.py:150-200]()
### 配置示例
```yaml
mode: b
llm:
provider: ollama
model: llama3.2
base_url: http://localhost:11434
api_key: "" # Ollama 本地无需 API Key
embedding:
provider: local
model: nomic-ai/nomic-embed-text-v1.5
device: cuda # 可选：cuda 或 cpu
```
对于 OpenAI 兼容 API：
```yaml
mode: b
llm:
provider: openai
base_url: https://api.openai.com/v1
model: gpt-4o-mini
api_key: sk-xxxxx # 重要：确保 API Key 正确配置
```
资料来源：[src/superlocalmemory/llm/backbone.py:80-120]()
### 已知问题
⚠️ **Issue #9**：Mode B 模式下 `api_key` 配置可能被静默丢弃
当使用非 Ollama 的 OpenAI 兼容 API 时，如果 `api_key` 配置不正确，`LLMBackbone.is_available()` 会返回 `False`，导致 LLM 功能不可用：
```python
# 问题代码位置
# src/superlocalmemory/core/config.py — SLMConfig.for_mode(), Mode B 分支
```
**临时解决方案**：
1. 确认 `api_key` 已正确写入配置文件
2. 检查 API 端点可访问性
3. 使用 `slm health` 命令验证 LLM 连接状态
资料来源：[Issue #9](https://github.com/qualixar/superlocalmemory/issues/9)
## Mode C：云端模式
### 工作原理
Mode C 将嵌入计算和 LLM 推理委托给云端服务，适用于没有本地 GPU 或需要更强算力的场景：
- **远程嵌入**：调用 OpenAI、Cohere 等嵌入 API
- **云端推理**：使用云端 LLM 进行复杂推理
- **数据主权**：重要数据仍存储在本地，仅在必要时调用云端
资料来源：[src/superlocalmemory/core/modes.py:80-120]()
### 配置示例
```yaml
mode: c
llm:
provider: openai
base_url: https://api.openai.com/v1
model: gpt-4o
api_key: sk-xxxxx
embedding:
provider: openai
model: text-embedding-3-small
api_key: sk-xxxxx
```
### 合规性考虑
Mode C 下所有发送到云端的数据都经过严格的隐私处理：
- 记忆内容在传输前进行加密
- 支持 EU AI Act 合规模式
- 完整的审计日志记录
资料来源：[src/superlocalmemory/compliance/eu_ai_act.py:100-150]()
## 模式切换与状态检查
### CLI 命令
```bash
# 切换运行模式
slm mode a # 切换到 Mode A
slm mode b # 切换到 Mode B
slm mode c # 切换到 Mode C
# 检查当前模式状态
slm status
# 健康检查（包含模式验证）
slm health
# 详细模式信息
slm config get mode
```
### Python API
```python
from superlocalmemory.core.config import SLMConfig
# 获取当前配置
config = SLMConfig.load()
# 切换模式
config.set_mode("a") # Mode A
config.set_mode("b") # Mode B
config.set_mode("c") # Mode C
# 保存配置
config.save()
```
资料来源：[src/superlocalmemory/cli/main.py:1-50]()
## 性能对比
```mermaid
graph LR
subgraph Mode_A["Mode A - 零LLM"]
A1[查询输入] --> A2[本地嵌入]
A2 --> A3[Fisher-Rao度量]
A3 --> A4[结果输出]
end
subgraph Mode_B["Mode B - 增强模式"]
B1[查询输入] --> B2[本地嵌入]
B2 --> B3[Ollama重排序]
B3 --> B4[结果输出]
end
subgraph Mode_C["Mode C - 云端模式"]
C1[查询输入] --> C2[云端嵌入]
C2 --> C3[云端LLM]
C3 --> C4[结果输出]
end
```
| 指标 | Mode A | Mode B | Mode C |
|------|--------|--------|--------|
| 首次响应时间 | <100ms | 200-500ms | 500ms+ |
| 内存占用 | ~200MB | ~2GB | ~500MB |
| 磁盘占用 | +嵌入模型 | +LLM模型 | 无额外 |
| 离线可用性 | ✅ 完全 | ✅ 基本 | ❌ 需要网络 |
| 检索精度 | 良好 | 优秀 | 优秀 |
资料来源：[src/superlocalmemory/server/unified_daemon.py:50-100]()
## 常见问题与解决方案
### 问题1：模式切换后无响应
**症状**：执行 `slm mode b` 后命令卡住或超时
**原因**：Mode B 需要 Ollama 服务运行，但服务未启动
**解决方案**：
```bash
# 启动 Ollama 服务
ollama serve &
# 验证 Ollama 状态
ollama list
# 再次切换模式
slm mode b
```
### 问题2：Mode B 下 LLM 功能不可用
**症状**：`slm recall` 返回结果但未进行 LLM 重排序
**排查步骤**：
```bash
# 1. 检查 LLM 可用性
slm health
# 2. 验证 API Key 配置
slm config get llm.api_key
# 3. 测试 Ollama 连接
curl http://localhost:11434/api/tags
```
**已知问题**：Issue #9 报告了 Mode B 下 `api_key` 被静默丢弃的问题，已在 v2.8.0 后修复
资料来源：[Issue #9](https://github.com/qualixar/superlocalmemory/issues/9)
### 问题3：Docker/Linux 环境下模式识别问题
**症状**：在 Docker 容器或 Linux 环境中模式功能异常
**解决方案**：
```bash
# 设置环境变量
export SLM_NON_INTERACTIVE=true
export SLM_HOME=/path/to/custom/directory
# 重新初始化
slm setup --force
```
资料来源：[Issue #26](https://github.com/qualixar/superlocalmemory/issues/26)
## 模式选择指南
```
graph TD
A[开始选择] --> B{是否有本地GPU?}
B -->|是| C{是否需要最高精度?}
B -->|否| D{是否需要离线使用?}
C -->|是| E[Mode C - 云端模式]
C -->|否| F{Memory占用要求?}
D -->|是| G[Mode A - 零LLM模式]
D -->|否| H{是否需要多语言?}
F -->|低| G
F -->|可接受| I[Mode B - 增强模式]
H -->|是| I
H -->|否| J{需要成本控制?}
J -->|是| G
J -->|否| I
```
### 推荐场景
| 场景 | 推荐模式 | 原因 |
|------|----------|------|
| 低配置设备 | Mode A | 资源占用最低 |
| 离线工作 | Mode A | 无网络依赖 |
| 开发测试 | Mode A/B | 成本低、易调试 |
| 生产环境 | Mode B | 精度与成本平衡 |
| 多语言场景 | Mode B/C | 本地嵌入更灵活 |
| 追求最高精度 | Mode C | 云端算力最强 |
## 多语言支持与嵌入端点配置
Mode B 和 Mode C 支持配置自定义嵌入端点，这对于非英语用户尤为重要：
```yaml
mode: b
embedding:
provider: openai_compatible
base_url: http://localhost:8080/v1
model: your-multilingual-model
api_key: xxxxx
```
此功能解决了 Issue #16 中用户对非英语语言支持的请求
资料来源：[Issue #16](https://github.com/qualixar/superlocalmemory/issues/16)
## 相关文档
- [快速入门指南](../Home)
- [安装与配置](../Installation)
- [常见问题解答](../FAQ)
- [架构设计](../Universal-Architecture)
- [MCP 集成](../MCP-Integration)
## 更新日志
| 版本 | 更新内容 |
|------|----------|
| v2.8.0 | 新增模式切换命令，修复 Mode B API Key 问题 |
| v2.7.0 | 优化 Mode A 检索算法，降低延迟 |
| v2.6.0 | 安全加固，模式隔离增强 |
资料来源：[src/superlocalmemory/core/modes.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/modes.py)
---
## CLI 参考手册
### 相关页面
相关主题：[快速入门](#page-getting-started), [MCP 工具集](#page-mcp-tools), [配置参考](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/cli/main.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
- [src/superlocalmemory/cli/commands.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/commands.py)
- [src/superlocalmemory/cli/daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/daemon.py)
- [src/superlocalmemory/cli/setup_wizard.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
- [src/superlocalmemory/cli/json_output.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/json_output.py)
- [src/superlocalmemory/server/unified_daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
# CLI 参考手册
SuperLocalMemory V3 提供了一个功能完整的命令行界面（CLI），允许用户通过 `slm` 命令与记忆系统进行交互。本页面详细说明了所有 CLI 命令的用法、参数选项以及常见使用场景。
---
## 概述
CLI 是 SuperLocalMemory 的核心交互方式，支持以下操作：
- **记忆存储**：使用 `slm remember` 命令存储新的记忆
- **语义检索**：使用 `slm recall` 命令进行四通道语义搜索
- **记忆管理**：删除、更新、遗忘不再需要的记忆
- **配置管理**：查看和修改系统配置
- **守护进程控制**：管理后台服务状态
- **数据导入**：批量导入外部数据
### 核心设计原则
CLI 采用以下设计原则：
1. **自动守护进程启动**：除特定命令外，大部分命令会自动确保守护进程运行
2. **首次使用引导**：首次运行任何命令时会自动触发设置向导
3. **原生 JSON 输出**：支持 `--json` 参数输出结构化数据，便于 AI Agent 集成
4. **跨平台支持**：支持 macOS、Windows、Linux
资料来源：[src/superlocalmemory/cli/main.py:95-112]()
---
## 命令行结构
```mermaid
graph TD
A["slm "] --> B["记忆命令"]
A --> C["管理命令"]
A --> D["配置命令"]
A --> E["系统命令"]
B --> B1["remember - 存储记忆"]
B --> B2["recall - 检索记忆"]
B --> B3["forget - 删除记忆"]
B --> B4["delete - 精确删除"]
B --> B5["update - 更新记忆"]
B --> B6["ingest - 批量导入"]
C --> C1["status - 系统状态"]
C --> C2["list - 列出记忆"]
C --> C3["profile - 配置切换"]
C --> C4["stats - 统计信息"]
D --> D1["config - 配置管理"]
D --> D2["mode - 模式切换"]
D --> D3["provider - 提供商设置"]
E --> E1["setup - 设置向导"]
E --> E2["daemon - 守护进程"]
E --> E3["disable/enable - 禁用/启用"]
E --> E4["migrate - 数据迁移"]
```
---
## 记忆操作命令
### slm remember — 存储记忆
存储新的记忆到系统中，支持多标签、项目分类和重要性评分。
```bash
slm remember "记忆内容" [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `fact` | 字符串 | 必需 | 要存储的记忆内容 |
| `--project` | 字符串 | 当前目录 | 项目标识符 |
| `--tag` | 字符串 | 无 | 逗号分隔的标签列表 |
| `--importance` | 整数 | 5 | 重要性评分 (1-10) |
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 使用示例
```bash
# 基础用法
slm remember "用户在登录页面遇到问题"
# 带标签和项目
slm remember "修复了支付模块的 bug" --project backend --tag bug,fixed --importance 8
# JSON 输出（适用于 AI Agent）
slm remember "用户偏好深色主题" --json
```
资料来源：[src/superlocalmemory/cli/main.py:45-62]()
---
### slm recall — 语义检索
使用四通道检索引擎（语义、词法、时间、结构）搜索记忆。
```bash
slm recall <查询> [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | 字符串 | 必需 | 搜索查询文本 |
| `--limit` | 整数 | 10 | 最大返回结果数 |
| `--json` | 标志 | false | 输出 JSON 格式 |
| `--fast` | 标志 | false | 跳过传播激活第五通道，获取亚秒级响应 |
#### 四通道检索说明
`slm recall` 使用 SuperLocalMemory 的核心检索算法：
1. **语义通道**：基于向量嵌入的语义相似度
2. **词法通道**：关键词匹配和短语匹配
3. **时间通道**：基于时间衰减的权重调整
4. **结构通道**：基于记忆之间的关联关系
使用 `--fast` 参数可跳过第五通道（传播激活），适用于工具调用前的快速检索场景。
#### 使用示例
```bash
# 基础搜索
slm recall "登录问题"
# 限制结果数量
slm recall "支付相关" --limit 5
# 快速模式（无传播激活）
slm recall "用户反馈" --fast
# JSON 输出
slm recall "bug 修复记录" --json
```
资料来源：[src/superlocalmemory/cli/main.py:64-77]()
---
### slm forget — 模糊删除
根据查询匹配删除记忆，使用模糊匹配算法。
```bash
slm forget <查询> [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | 字符串 | 必需 | 用于匹配的查询文本 |
| `--dry-run` | 标志 | false | 预览匹配结果但不删除 |
| `--yes`, `-y` | 标志 | false | 跳过确认提示 |
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 使用示例
```bash
# 预览将要删除的内容
slm forget "临时测试记忆" --dry-run
# 确认删除
slm forget "旧项目数据" --yes
# JSON 输出
slm forget "废弃代码" --json
```
资料来源：[src/superlocalmemory/cli/main.py:79-87]()
---
### slm delete — 精确删除
根据记忆 ID 精确删除单条记忆。
```bash
slm delete [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `fact_id` | 字符串 | 必需 | 要删除的记忆 ID |
| `--yes`, `-y` | 标志 | false | 跳过确认提示 |
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 使用示例
```bash
# 删除指定 ID 的记忆
slm delete abc123def456
# 跳过确认
slm delete abc123def456 -y
```
---
### slm update — 更新记忆
更新现有记忆的内容和元数据。
```bash
slm update [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `fact_id` | 字符串 | 必需 | 要更新的记忆 ID |
| `--content` | 字符串 | 必需 | 新的记忆内容 |
| `--tag` | 字符串 | 无 | 逗号分隔的标签 |
| `--importance` | 整数 | 无 | 新的重要性评分 |
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 使用示例
```bash
# 更新记忆内容
slm update abc123def456 --content "修正后的记忆内容"
# 更新多个字段
slm update abc123def456 --content "新内容" --tag updated --importance 9
```
---
### slm ingest — 批量导入
从文件或目录批量导入记忆内容。
```bash
slm ingest [路径] [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | 字符串 | 当前目录 | 要导入的文件或目录 |
| `--dry-run` | 标志 | false | 预览导入内容但不写入 |
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 支持的文件格式
- Markdown 文件 (.md)
- 文本文件 (.txt)
- JSON 文件 (.json)
- 代码文件（自动提取注释）
#### 使用示例
```bash
# 导入整个项目目录
slm ingest ./my-project
# 预览导入
slm ingest ./docs --dry-run
# JSON 输出
slm ingest ./notes --json
```
---
## 配置管理命令
### slm config — 配置查看与修改
查看和修改 SuperLocalMemory 配置，支持点号表示法。
```bash
slm config [value] [选项]
```
#### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `action` | 字符串 | 必需 | 操作类型：`get` 或 `set` |
| `key` | 字符串 | 必需 | 配置键名（点号表示法，如 `evolution.enabled`） |
| `value` | 字符串 | 无 | 要设置的值（仅 `set` 操作需要） |
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 配置键示例
```bash
# 查看配置
slm config get evolution.enabled
slm config get llm.model
# 修改配置
slm config set evolution.enabled true
slm config set evolution.enabled false
```
资料来源：[src/superlocalmemory/cli/main.py:100-110]()
---
### slm mode — 模式切换
切换 SuperLocalMemory 的运行模式。
```bash
slm mode [mode_name]
```
#### 可用模式
| 模式 | 说明 |
|------|------|
| `A` | 完全本地模式，使用本地模型 |
| `B` | 混合模式，支持 API 调用 |
| `local` | 仅使用本地资源 |
#### 使用示例
```bash
# 查看当前模式
slm mode
# 切换到 Mode B
slm mode B
```
---
### slm provider — 提供商配置
配置 LLM 提供商设置。
```bash
slm provider [名称]
```
---
## 系统管理命令
### slm status — 系统状态
查看 SuperLocalMemory 系统的运行状态。
```bash
slm status [选项]
```
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--json` | 标志 | false | 输出 JSON 格式 |
#### 使用示例
```bash
# 查看状态
slm status
# JSON 输出
slm status --json
```
---
### slm disable — 禁用 SLM
全局禁用 SuperLocalMemory，停止守护进程并创建禁用标记文件。
```bash
slm disable
```
执行后会：
1. 创建 `~/.superlocalmemory/.disabled` 文件
2. 停止后台守护进程
3. 所有 CLI 命令将不可用
#### 使用示例
```bash
# 禁用 SLM
slm disable
```
资料来源：[src/superlocalmemory/cli/main.py:130-134]()
---
### slm enable — 启用 SLM
重新启用被禁用的 SuperLocalMemory。
```bash
slm enable
```
#### 使用示例
```bash
# 启用 SLM
slm enable
```
---
### slm setup — 设置向导
启动交互式设置向导，配置 SuperLocalMemory。
```bash
slm setup
```
设置向导会：
1. 检测环境并下载必要的模型
2. 配置运行模式
3. 验证安装完整性
#### 首次使用自动触发
首次运行任何 `slm` 命令时，设置向导会自动触发。静默安装可通过设置 `SLM_NON_INTERACTIVE=1` 环境变量禁用交互提示。
资料来源：[src/superlocalmemory/cli/setup_wizard.py:35-48]()
---
### slm rotate-token — 轮换安装令牌
轮换 SLM 安装令牌，增强安全性。
```bash
slm rotate-token
```
轮换后需要执行 `slm restart` 重启守护进程使更改生效。
---
## 守护进程管理
### 自动守护进程启动
SuperLocalMemory CLI 采用「常驻」设计哲学：守护进程会在需要时自动启动，关闭笔记本电脑、重启或崩溃后会自动恢复。
```mermaid
graph LR
A["slm 命令"] --> B{"命令类型?"}
B -->|需要守护进程| C["ensure_daemon()"]
C --> D["守护进程运行中?"]
D -->|否| E["启动守护进程"]
D -->|是| F["使用现有守护进程"]
B -->|不需要守护进程| G["setup, mode, config..."]
E --> H["继续执行命令"]
F --> H
G --> H
```
#### 不自动启动守护进程的命令
以下命令不会触发守护进程自动启动：
- `setup`
- `mode`
- `provider`
- `connect`
- `migrate`
- `mcp`
- `warmup`
- `config`
- `evolve`
- `db`
- `disable`
- `enable`
- `clear-cache`
- `reconfigure`
- `benchmark`
- `rotate-token`
资料来源：[src/superlocalmemory/cli/main.py:95-112]()
---
### slm restart — 重启守护进程
重启 SuperLocalMemory 守护进程。
```bash
slm restart
```
---
## JSON 输出格式
所有支持 `--json` 参数的命令都遵循 2026 Agent 原生 CLI 标准，使用统一的 JSON 响应包装器。
### 响应结构
```json
{
"success": true,
"command": "recall",
"version": "3.4.58",
"data": {
"results": [...]
},
"hateoas": {
"next_actions": [
{"action": "remember", "example": "slm remember ..."}
]
}
}
```
### 版本获取优先级
JSON 响应中的版本号按以下顺序获取：
1. `package.json`（npm 安装）
2. `pyproject.toml`（pip 安装）
3. `importlib.metadata`（备选）
资料来源：[src/superlocalmemory/cli/json_output.py:30-55]()
---
## 环境变量
SuperLocalMemory CLI 支持以下环境变量：
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `SLM_NON_INTERACTIVE` | 禁用交互提示，用于 CI/CD 环境 | 未设置（启用交互） |
| `SL_MEMORY_PATH` | 自定义 SuperLocalMemory 数据目录 | `~/.superlocalmemory` |
| `CI` | CI 环境检测，启用时禁用交互式功能 | 未设置 |
#### 使用示例
```bash
# 在 CI 环境中运行
export CI=true
slm recall "测试查询"
# 自定义数据目录
export SL_MEMORY_PATH=/data/slm
slm status
# 禁用交互提示
export SLM_NON_INTERACTIVE=1
slm setup
```
资料来源：[src/superlocalmemory/cli/setup_wizard.py:25-30]()
---
## 常见问题与解决方案
### slm remember 无响应
如果在运行 `slm remember` 时长时间无响应，可能是守护进程未正常启动。解决方案：
1. 手动启动守护进程：`slm daemon start`
2. 检查日志：`slm status`
3. 如果问题持续，可能是 v3.3.19 之前的版本，升级后可解决
此问题已在 v3.3.19 版本中修复。
### 首次运行卡住
首次使用时会触发设置向导，需要下载嵌入模型。如果网络较慢，可以：
1. 设置 `SLM_NON_INTERACTIVE=1` 跳过交互
2. 预先手动下载模型
3. 使用代理或镜像源
### 守护进程绑定地址问题
当前版本守护进程硬编码绑定到 `127.0.0.1`。如需远程访问，可通过反向代理或端口转发实现。
---
## 详见
- [安装指南](Installation)
- [架构说明](Universal-Architecture)
- [MCP 集成](MCP-Integration)
- [通用技能](Universal-Skills)
- [常见问题](FAQ)
---
## MCP 工具集
### 相关页面
相关主题：[CLI 参考手册](#page-cli-reference), [快速入门](#page-getting-started)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/mcp-tools.md](https://github.com/qualixar/superlocalmemory/blob/main/docs/mcp-tools.md)
- [src/superlocalmemory/mcp/tools.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools.py)
- [src/superlocalmemory/mcp/tools_core.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools_core.py)
- [src/superlocalmemory/mcp/tools_mesh.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools_mesh.py)
- [src/superlocalmemory/mcp/server.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/server.py)
- [ide/configs/claude-desktop-mcp.json](https://github.com/qualixar/superlocalmemory/blob/main/ide/configs/claude-desktop-mcp.json)
- [ide/configs/cursor-mcp.json](https://github.com/qualixar/superlocalmemory/blob/main/ide/configs/cursor-mcp.json)
- [package.json](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
# MCP 工具集
SuperLocalMemory 通过 MCP（Model Context Protocol）协议提供了一套完整的本地记忆工具集，使 AI 助手能够安全、高效地存储和检索个人记忆。本文档详细介绍 MCP 工具集的设计架构、可用工具、配置方法以及常见使用场景。
## 概述
MCP 工具集是 SuperLocalMemory V3 的核心组件之一，通过标准化的 MCP 协议与各种 AI 工具和 IDE 进行集成。根据 `package.json` 中的配置，MCP 服务器名称为 `io.github.qualixar/superlocalmemory`，支持 11 种以上的 IDE 集成，包括 Claude Desktop、Cursor、Windsurf、Continue.dev 等主流 AI 编程工具。
```mermaid
graph LR
A["AI 工具/IDE"] --> B["MCP 客户端"]
B --> C["SuperLocalMemory MCP 服务器"]
C --> D["V3 MemoryEngine"]
D --> E[".sqlite 数据库"]
style C fill:#e1f5fe
style D fill:#fff3e0
style E fill:#e8f5e9
```
资料来源：[package.json:17](https://github.com/qualixar/superlocalmemory/blob/main/package.json)
## MCP 服务器架构
### 服务端组件
MCP 服务器采用模块化设计，核心组件分布在多个源码文件中：
| 组件 | 文件路径 | 功能描述 |
|------|----------|----------|
| MCP 服务器入口 | `src/superlocalmemory/mcp/server.py` | FastMCP 服务器初始化和路由注册 |
| 核心工具集 | `src/superlocalmemory/mcp/tools_core.py` | 基础记忆操作工具（remember/recall/list） |
| Mesh 工具集 | `src/superlocalmemory/mcp/tools_mesh.py` | 分布式记忆同步工具 |
| 工具注册 | `src/superlocalmemory/mcp/tools.py` | 工具装饰器和注册逻辑 |
资料来源：[src/superlocalmemory/mcp/server.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/server.py)
### 工具注册机制
工具通过 `@mcp.tool()` 装饰器注册到 MCP 服务器。每个工具都是一个异步函数，返回结构化的 JSON 响应：
```python
@mcp.tool()
async def slm_remember(
content: str,
profile: Optional[str] = None,
importance: int = 5,
tags: Optional[list[str]] = None,
project: Optional[str] = None,
) -> Annotated[str, ReadAnnotations()]:
"""存储新的记忆条目"""
# 实现代码
```
资料来源：[src/superlocalmemory/mcp/tools.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools.py)
## 核心工具详解
### 1. slm_remember — 记忆存储
`slm_remember` 工具用于将信息存储到本地记忆系统。
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| content | string | ✅ | — | 要存储的记忆内容 |
| profile | string | ❌ | 当前激活profile | 所属用户profile |
| importance | integer | ❌ | 5 | 重要性评分（1-10） |
| tags | string[] | ❌ | [] | 标签列表用于分类 |
| project | string | ❌ | "default" | 关联项目名称 |
**返回结果：**
```json
{
"id": "mem_abc123",
"content": "用户提供的记忆内容",
"importance": 5,
"tags": ["标签1", "标签2"],
"project": "my-project",
"created_at": 1703123456
}
```
资料来源：[src/superlocalmemory/mcp/tools_core.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools_core.py)
### 2. slm_recall — 记忆检索
`slm_recall` 工具支持基于语义相似度的记忆检索，使用 Fisher-Rao 度量进行信息几何相似度计算。
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | ✅ | — | 检索查询文本 |
| profile | string | ❌ | 当前激活profile | 检索范围限定 |
| limit | integer | ❌ | 10 | 返回结果数量上限 |
| min_importance | integer | ❌ | 1 | 最低重要性阈值 |
**返回结果：**
```json
{
"results": [
{
"id": "mem_abc123",
"content": "记忆内容",
"similarity": 0.87,
"importance": 7,
"tags": ["相关标签"],
"recency_score": 0.65
}
],
"total_found": 15,
"query_time_ms": 42
}
```
资料来源：[src/superlocalmemory/mcp/tools_core.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools_core.py)
### 3. slm_list_recent — 最近记忆
列出最近添加的记忆条目，按时间倒序排列。
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| profile | string | ❌ | 当前激活profile | 限定profile范围 |
| limit | integer | ❌ | 20 | 返回数量（最大100） |
| since_timestamp | integer | ❌ | null | 仅返回指定时间后的记录 |
### 4. slm_status — 系统状态
获取 SuperLocalMemory 系统的运行状态和统计信息。
**返回结果：**
```json
{
"version": "3.4.58",
"daemon_running": true,
"profile": "default",
"stats": {
"total_memories": 1847,
"active_profiles": 3,
"cache_size_mb": 12.4,
"last_sync": "2026-02-10T14:30:00Z"
}
}
```
### 5. slm_build_graph — 知识图谱构建
基于已有记忆构建知识图谱结构，展示记忆之间的关联关系。
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| root_memory_id | string | ❌ | null | 起始记忆节点 |
| depth | integer | ❌ | 3 | 图谱遍历深度 |
| include_weak_links | boolean | ❌ | false | 是否包含弱关联 |
### 6. slm_switch_profile — Profile 切换
在不同的用户 profile 之间切换，改变记忆检索的作用域。
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| profile_name | string | ✅ | — | 目标profile名称 |
资料来源：[src/superlocalmemory/mcp/tools.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools.py)
## Mesh 工具集
Mesh 工具集用于分布式场景，支持多机器间的记忆同步。当与 slm-mesh 配合使用时，可以实现跨设备的统一记忆访问。
### 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `slm_mesh_share` | 将指定记忆共享给其他节点 |
| `slm_mesh_pull` | 从远程节点拉取共享记忆 |
| `slm_mesh_sync` | 执行增量同步操作 |
资料来源：[src/superlocalmemory/mcp/tools_mesh.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/mcp/tools_mesh.py)
```mermaid
graph TD
A["本地节点"] --> B["slm_mesh_share"]
B --> C["slm-mesh Broker"]
C --> D["远程节点 A"]
C --> E["远程节点 B"]
F["远程节点 A"] --> G["slm_mesh_pull"]
G --> C
style B fill:#e3f2fd
style G fill:#e3f2fd
style C fill:#fff3e0
```
## IDE 配置指南
### Claude Desktop
在 `~/.config/Claude/projects/` 或 `~/Library/Application Support/Claude/` 目录下创建或编辑 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"superlocalmemory": {
"command": "npx",
"args": ["-y", "@qualixar/superlocalmemory"],
"env": {
"SLM_PROFILE": "default",
"SLM_HOST": "127.0.0.1",
"SLM_PORT": "8765"
}
}
}
}
```
资料来源：[ide/configs/claude-desktop-mcp.json](https://github.com/qualixar/superlocalmemory/blob/main/ide/configs/claude-desktop-mcp.json)
### Cursor IDE
编辑 Cursor 设置中的 MCP 配置，添加以下配置项：
```json
{
"mcpServers": {
"superlocalmemory": {
"command": "superlocalmemory",
"args": ["mcp", "run"],
"env": {
"SLM_PROFILE": "default"
}
}
}
}
```
资料来源：[ide/configs/cursor-mcp.json](https://github.com/qualixar/superlocalmemory/blob/main/ide/configs/cursor-mcp.json)
### 其他支持的 IDE
根据项目文档，MCP 工具集还支持以下 IDE 和工具：
| IDE/工具 | 配置方式 | 支持状态 |
|----------|----------|----------|
| Windsurf | MCP JSON 配置 | ✅ 官方支持 |
| Continue.dev | MCP JSON 配置 | ✅ 官方支持 |
| ChatGPT | MCP JSON 配置 | ✅ 官方支持 |
| Perplexity | MCP JSON 配置 | ✅ 官方支持 |
| Zed | MCP JSON 配置 | ✅ 官方支持 |
| OpenCode | MCP JSON 配置 | ✅ 官方支持 |
| Antigravity | MCP JSON 配置 | ✅ 官方支持 |
| Cody | MCP JSON 配置 | ✅ 官方支持 |
| Aider | MCP JSON 配置 | ✅ 官方支持 |
资料来源：[docs/mcp-tools.md](https://github.com/qualixar/superlocalmemory/blob/main/docs/mcp-tools.md)
## 环境变量配置
MCP 工具集通过以下环境变量进行配置：
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `SLM_PROFILE` | "default" | 默认使用的 profile |
| `SLM_HOST` | "127.0.0.1" | MCP 服务绑定地址 |
| `SLM_PORT` | "8765" | MCP 服务监听端口 |
| `SLM_DATA_DIR` | `~/.superlocalmemory` | 数据存储目录 |
| `SLM_API_KEY` | null | API 认证密钥（生产环境建议设置） |
| `SLM_NON_INTERACTIVE` | false | 非交互模式标志 |
**注意事项：**
- 社区反馈 issue #23 指出 SLM_HOST 在某些分布式场景下硬编码为 127.0.0.1，对于多机器 WireGuard mesh 环境可能需要修改为 `0.0.0.0` 以支持远程连接。
- issue #10 报告 `SLM_DATA_DIR` 虽然在文档中提及但早期版本未完全实现，现版本已支持。
资料来源：[src/superlocalmemory/cli/setup_wizard.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
## 工作流程示例
### 基本使用流程
```mermaid
sequenceDiagram
participant User as 用户
participant IDE as AI IDE
participant MCP as MCP 客户端
participant SLM as SLM 服务器
participant DB as SQLite DB
User->>IDE: 提问或请求
IDE->>MCP: 调用 slm_recall 检索记忆
MCP->>SLM: HTTP 请求 /api/recall
SLM->>DB: 向量相似度查询
DB-->>SLM: 返回匹配记忆
SLM-->>MCP: JSON 结果
MCP-->>IDE: 结构化记忆
IDE-->>User: 基于记忆的回答
User->>IDE: 确认重要信息
IDE->>MCP: 调用 slm_remember 存储
MCP->>SLM: HTTP 请求 /api/remember
SLM->>DB: 插入新记忆
DB-->>SLM: 确认写入
SLM-->>MCP: 成功响应
MCP-->>IDE: 确认消息
IDE-->>User: 存储成功提示
```
### 异步预热机制
根据 `src/superlocalmemory/server/routes/prewarm.py` 的设计，每次工具调用后会自动触发预热机制，将上下文缓存到活跃脑缓存（active_brain_cache）中：
1. 工具调用完成后，POST 到 `/internal/prewarm`
2. 计算 topic_sig（话题签名）
3. 提取 fact_ids（相关事实 ID）
4. 更新 `ContextCache` 中的缓存条目
资料来源：[src/superlocalmemory/server/routes/prewarm.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/routes/prewarm.py)
## 安全考虑
### Profile 隔离
根据 v2.6.0 安全加固版本的设计，所有 MCP 查询端点都实现了 profile 隔离。一个 profile 的记忆永远不会泄露到另一个 profile，即使使用相同的 MCP 连接。
```python
# 每个查询都会自动注入当前 profile 上下文
query_context = {
"profile": current_profile,
"isolation_enforced": True,
"audit_trail": True
}
```
### Trust 框架
V3 引入了 Trust 框架，对 MCP 工具调用进行权限校验：
| 权限级别 | 可用工具 | 说明 |
|----------|----------|------|
| TRUST_LOW | slm_recall, slm_list_recent | 仅读操作 |
| TRUST_MEDIUM | + slm_remember | 可添加新记忆 |
| TRUST_HIGH | + slm_build_graph | 可构建知识图谱 |
| TRUST_ADMIN | 所有工具 | 完全访问权限 |
## 常见问题与故障排除
### 问题 1：slm remember 无响应
社区 issue #11 报告在某些环境下 `slm remember` 命令长时间等待无响应。该问题已在 **v3.3.19** 版本中修复。
**排查步骤：**
1. 检查 SLM 服务是否运行：`slm status`
2. 验证 MCP 连接配置是否正确
3. 查看服务端日志：`tail -f ~/.superlocalmemory/logs/slm.log`
4. 确认 Ollama 或 LLM 后端服务可用
### 问题 2：Mode B 下 api_key 被忽略
Issue #9 报告 Mode B 配置中 `api_key` 参数被静默丢弃，导致非 Ollama 提供商（如 localai）无法正常工作。
**临时解决方案：**
在环境变量中直接设置：
```bash
export OPENAI_API_KEY="your-key-here"
```
### 问题 3：Docker 容器中认知整合问题
Issue #26 报告在 Ubuntu/Debian Docker 容器环境中出现认知整合和追踪问题。建议在容器中设置适当的工作目录和挂载点：
```bash
docker run -v ~/.superlocalmemory:/root/.superlocalmemory \
-e SLM_DATA_DIR=/root/.superlocalmemory \
your-slm-image
```
## 性能优化建议
### 缓存策略
MCP 工具集利用 `ContextCache` 进行热点数据缓存：
| 缓存策略 | 说明 |
|----------|------|
| 预热缓存 | 工具调用后自动写入 |
| LRU 淘汰 | 最近最少使用原则 |
| TTL 过期 | 默认 5 分钟自动失效 |
### 并发限制
| 端点类型 | 速率限制 |
|----------|----------|
| 写入操作（remember） | 每 60 秒最多 30 次 |
| 读取操作（recall） | 每 60 秒最多 120 次 |
资料来源：[src/superlocalmemory/server/ui.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
## 相关文档
- [Universal Architecture（通用架构）](Universal-Architecture) — 了解 SuperLocalMemory 的 7 层架构设计
- [Installation（安装指南）](Installation) — 详细的安装和配置教程
- [Home（首页）](Home) — 项目概览和主要特性
- [FAQ（常见问题）](FAQ) — 更多常见问题解答
## 更新日志
| 版本 | 更新内容 |
|------|----------|
| v3.4.x | 异步预热机制、4 通道检索 |
| v3.3.19 | 修复 slm remember 无响应问题 |
| v2.8.0 | 新增 Memory Lifecycle 管理 |
| v2.6.0 | 安全加固，Profile 隔离 |
| v2.1.0 | MCP 集成层正式发布 |
---
**创作者：** Varun Pratap Bhardwaj
**项目地址：** [https://github.com/qualixar/superlocalmemory](https://github.com/qualixar/superlocalmemory)
**许可证：** AGPL-3.0-or-later
---
## 检索管道
### 相关页面
相关主题：[V3 架构](#page-architecture), [记忆生命周期](#page-memory-lifecycle)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/retrieval/engine.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/engine.py)
- [src/superlocalmemory/retrieval/semantic_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/semantic_channel.py)
- [src/superlocalmemory/retrieval/hopfield_channel.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/hopfield_channel.py)
- [src/superlocalmemory/retrieval/spreading_activation.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/retrieval/spreading_activation.py)
- [src/superlocalmemory/core/embeddings.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/embeddings.py)
- [src/superlocalmemory/math/fisher.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/math/fisher.py)
# 检索管道
SuperLocalMemory 的检索管道（Retrieval Pipeline）是系统的核心组件，负责从本地向量数据库中高效召回与用户查询最相关的记忆条目。该管道采用**四通道并行检索架构**，结合语义相似度、Hopfield 网络联想检索、扩散激活传播以及 Fisher-Rao 信息几何相似度，为 AI 代理提供数学可证明的精确记忆召回能力。
## 1. 架构概述
### 1.1 四通道检索模型
SuperLocalMemory V3 采用创新的四通道并行检索架构，每个通道从不同维度评估记忆与查询的相关性：
```mermaid
graph TD
A[用户查询] --> B[检索引擎]
B --> C1[语义通道
Semantic Channel]
B --> C2[Hopfield通道
Hopfield Channel]
B --> C3[扩散激活通道
Spreading Activation]
B --> C4[Fisher-Rao通道
Fisher-Rao Metric]
C1 --> D[通道得分]
C2 --> D
C3 --> D
C4 --> D
D --> E[得分融合]
E --> F[Top-K 记忆条目]
```
### 1.2 核心组件列表
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| 检索引擎 | `src/superlocalmemory/retrieval/engine.py` | 协调四通道并行执行、得分融合、结果排序 |
| 语义通道 | `src/superlocalmemory/retrieval/semantic_channel.py` | 基于嵌入向量的余弦相似度检索 |
| Hopfield 通道 | `src/superlocalmemory/retrieval/hopfield_channel.py` | 联想记忆检索，模拟人类关联思维 |
| 扩散激活 | `src/superlocalmemory/retrieval/spreading_activation.py` | 图传播算法，基于记忆网络拓扑检索 |
| 嵌入生成 | `src/superlocalmemory/core/embeddings.py` | 生成查询和记忆的向量表示 |
| Fisher-Rao 度量 | `src/superlocalmemory/math/fisher.py` | 信息几何空间的相似度计算 |
## 2. 检索引擎
### 2.1 引擎架构
检索引擎是整个管道的中枢，负责接收用户查询、协调四个通道并行执行、对通道得分进行加权融合，并返回最终排序结果。
```mermaid
graph LR
A[Query] --> B[Embedding]
B --> C[并行调度]
C --> D1[语义通道]
C --> D2[Hopfield通道]
C --> D3[扩散激活]
C --> D4[Fisher-Rao]
D1 --> E[得分归一化]
D2 --> E
D3 --> E
D4 --> E
E --> F[加权融合]
F --> G[重排序]
G --> H[Top-K Results]
```
### 2.2 检索执行流程
```python
# 资料来源：src/superlocalmemory/retrieval/engine.py
async def retrieve(self, query: str, top_k: int = 10, **kwargs) -> List[MemoryEntry]:
"""
执行四通道并行检索
参数:
query: 用户查询文本
top_k: 返回的顶级结果数量
**kwargs: 传递给各通道的额外参数
返回:
按融合得分排序的记忆条目列表
"""
```
### 2.3 得分融合机制
引擎采用加权几何平均方式融合四通道得分：
```python
# 资料来源：src/superlocalmemory/retrieval/engine.py
def _fuse_scores(self, channel_scores: Dict[str, np.ndarray]) -> np.ndarray:
"""加权几何平均融合多通道得分"""
weights = self.channel_weights # 各通道权重配置
fused = np.ones_like(list(channel_scores.values())[0])
for channel_name, scores in channel_scores.items():
fused *= np.power(scores, weights.get(channel_name, 1.0))
return np.power(fused, 1.0 / sum(weights.values()))
```
## 3. 语义通道
### 3.1 嵌入向量检索
语义通道基于向量嵌入的余弦相似度进行记忆召回。每个记忆条目在存储时会被转换为高维向量表示，查询同样被编码为向量，然后通过向量相似度搜索找到最相关的记忆。
```mermaid
graph TD
A[查询文本] --> B[Embedding 模型]
C1[记忆1] --> D1[Embedding]
C2[记忆2] --> D2[Embedding]
C3[记忆3] --> D3[Embedding]
B --> E[余弦相似度计算]
D1 --> E
D2 --> E
D3 --> E
E --> F[相似度得分排序]
```
### 3.2 嵌入配置参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `embedding_model` | `nomic-ai/nomic-embed-text-v1.5` | 嵌入模型名称 |
| `embedding_dimension` | 768 | 嵌入向量维度 |
| `similarity_metric` | `cosine` | 相似度度量方式 |
| `batch_size` | 32 | 批处理大小 |
### 3.3 实现源码
```python
# 资料来源：src/superlocalmemory/retrieval/semantic_channel.py
class SemanticChannel:
"""基于语义嵌入的记忆检索通道"""
async def retrieve(
self,
query_embedding: np.ndarray,
memory_embeddings: List[np.ndarray],
top_k: int = 10
) -> List[Tuple[int, float]]:
"""返回记忆索引和相似度得分列表"""
similarities = cosine_similarity(
[query_embedding],
memory_embeddings
)[0]
# 获取 Top-K 结果
top_indices = np.argsort(similarities)[-top_k:][::-1]
return [(int(idx), float(similarities[idx])) for idx in top_indices]
```
## 4. Hopfield 通道
### 4.1 联想记忆检索
Hopfield 通道模拟人类大脑的联想记忆机制。当用户查询某个概念时，该通道能够检索与该概念具有关联关系但字面上不包含查询词的记忆条目。
```mermaid
graph LR
A[查询模式] --> B[Hopfield 网络]
B --> C[能量函数最小化]
C --> D[收敛到吸引子]
D --> E[关联记忆输出]
F[记忆模式
M1, M2, M3...] --> B
```
### 4.2 Hopfield 网络参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `memory_capacity` | 1000 | 网络可存储的最大模式数 |
| `stability_threshold` | 0.01 | 收敛稳定性阈值 |
| `max_iterations` | 100 | 最大迭代次数 |
| `temperature` | 1.0 | 模拟退火温度参数 |
### 4.3 实现原理
```python
# 资料来源：src/superlocalmemory/retrieval/hopfield_channel.py
class HopfieldChannel:
"""
基于 Hopfield 网络的联想记忆检索
使用能量函数 E = -0.5 * sum(W_ij * s_i * s_j) 进行模式检索
通过异步或同步更新使网络收敛到能量局部最小值
"""
def _compute_energy(self, state: np.ndarray) -> float:
"""计算当前状态的能量"""
return -0.5 * np.dot(state, np.dot(self.weights, state))
async def retrieve(self, query: np.ndarray, top_k: int = 10) -> List[Tuple[str, float]]:
"""联想检索：返回与查询关联的记忆"""
state = query.copy()
# 迭代收敛
for _ in range(self.max_iterations):
new_state = np.tanh(np.dot(self.weights, state) + self.bias)
if np.max(np.abs(new_state - state)) < self.stability_threshold:
break
state = new_state
# 计算与存储模式的相似度
similarities = np.dot(self.memory_patterns, state)
return self._get_top_k(similarities, top_k)
```
## 5. 扩散激活通道
### 5.1 图传播算法
扩散激活通道基于记忆之间的语义关系图进行传播检索。当查询激活某个节点时，激活信号会沿着图中的边传播到相邻节点，从而发现间接相关的记忆。
```mermaid
graph TD
A[查询节点] -->|初始激活| B[Node A]
B -->|扩散| C[Node B]
B -->|扩散| D[Node C]
C -->|继续扩散| E[Node D]
D -->|继续扩散| F[Node E]
C -->|边权重| G[0.8]
D -->|边权重| H[0.6]
E -->|激活累积| I[最终得分]
F -->|激活累积| I
```
### 5.2 扩散参数配置
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `damping_factor` | 0.85 | 激活信号的衰减系数 |
| `max_hops` | 3 | 最大传播跳数 |
| `threshold` | 0.01 | 最小激活阈值 |
| `convergence_tolerance` | 1e-6 | 收敛容差 |
### 5.3 实现细节
```python
# 资料来源：src/superlocalmemory/retrieval/spreading_activation.py
class SpreadingActivation:
"""
基于扩散激活的图检索算法
使用 PageRank 风格的迭代传播:
activation[node] = (1-d) * initial + d * sum(adjacent_activation * weight)
"""
def __init__(self, graph: nx.Graph, damping: float = 0.85):
self.graph = graph
self.damping = damping
self.nodes = list(graph.nodes())
self.adjacency = self._build_adjacency_matrix()
async def retrieve(
self,
query_nodes: List[str],
top_k: int = 10
) -> List[Tuple[str, float]]:
"""执行扩散激活检索"""
# 初始化激活值
activation = np.zeros(len(self.nodes))
for node in query_nodes:
if node in self.nodes:
activation[self.nodes.index(node)] = 1.0
# 迭代扩散直到收敛
for _ in range(self.max_hops):
new_activation = (1 - self.damping) * activation
new_activation += self.damping * np.dot(self.adjacency, activation)
if np.sum(np.abs(new_activation - activation)) < self.convergence_tolerance:
break
activation = new_activation
# 返回 Top-K 结果
return self._rank_results(activation, top_k)
```
## 6. Fisher-Rao 通道
### 6.1 信息几何相似度
Fisher-Rao 通道使用信息几何框架计算概率分布之间的测地线距离，提供数学上最优的相似度度量。与传统的欧氏距离或余弦相似度不同，Fisher-Rao 度量考虑了概率分布的黎曼几何结构。
```mermaid
graph LR
A[分布 P] -->|参数θ| B[流形 M]
C[分布 Q] -->|参数φ| B
B -->|测地线| D[最短路径]
D -->|长度| E[Fisher-Rao 距离]
```
### 6.2 Fisher 信息度量
```python
# 资料来源：src/superlocalmemory/math/fisher.py
class FisherRaoMetric:
"""
Fisher-Rao 信息几何度量实现
对于概率分布族 {p(x;θ)}，Fisher 信息矩阵 G(θ) 定义为:
G_ij(θ) = E[∂_i log p(x;θ) · ∂_j log p(x;θ)]
两点 θ1, θ2 之间的 Fisher-Rao 距离:
d(θ1, θ2) = arccos(√(F(θ1, θ2)))
其中 F 为 Fisher 相关系数
"""
def compute_fisher_information(self, distribution: np.ndarray) -> np.ndarray:
"""计算 Fisher 信息矩阵"""
log_p = np.log(distribution + 1e-10)
grad_log_p = np.gradient(log_p)
return np.outer(grad_log_p, grad_log_p)
def compute_distance(self, p: np.ndarray, q: np.ndarray) -> float:
"""计算 Fisher-Rao 距离"""
# 确保归一化
p = p / np.sum(p)
q = q / np.sum(q)
# 计算 Fisher 相关系数
sqrt_p = np.sqrt(p)
sqrt_q = np.sqrt(q)
fisher_corr = np.sum(sqrt_p * sqrt_q)
# 转换为距离
return np.arccos(np.clip(fisher_corr, 0, 1))
```
### 6.3 度量参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `smoothing_epsilon` | 1e-10 | 数值稳定性参数 |
| `max_geodesic_steps` | 50 | 测地线近似最大步数 |
| `approximation_threshold` | 0.9999 | 高相似度近似阈值 |
## 7. 配置与调优
### 7.1 检索配置选项
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `retrieval.top_k` | int | 10 | 返回的最多记忆条目数 |
| `retrieval.min_score` | float | 0.0 | 最小 relevance 阈值 |
| `retrieval.timeout_ms` | int | 5000 | 检索超时（毫秒） |
| `channel_weights.semantic` | float | 0.3 | 语义通道权重 |
| `channel_weights.hopfield` | float | 0.25 | Hopfield 通道权重 |
| `channel_weights.spreading` | float | 0.25 | 扩散激活权重 |
| `channel_weights.fisher_rao` | float | 0.2 | Fisher-Rao 通道权重 |
### 7.2 模式选择
```python
# 资料来源：src/superlocalmemory/retrieval/engine.py
class RetrievalMode(Enum):
"""检索模式配置"""
FULL = "full" # 四通道全开
SEMANTIC_ONLY = "semantic_only" # 仅语义检索
FAST = "fast" # 快速模式（仅语义+扩散）
PRECISE = "precise" # 精确模式（增加迭代次数）
# 使用示例
result = await engine.retrieve(
query="查找最近的 Python 项目",
mode=RetrievalMode.FAST,
top_k=5
)
```
### 7.3 环境变量配置
| 环境变量 | 说明 |
|----------|------|
| `SLM_EMBEDDING_MODEL` | 覆盖默认嵌入模型 |
| `SLM_EMBEDDING_ENDPOINT` | 自定义嵌入 API 端点（OpenAI 兼容） |
| `SLM_DATA_DIR` | 数据目录路径 |
| `SLM_TIMEOUT` | 检索操作超时时间 |
## 8. 使用模式
### 8.1 CLI 检索
```bash
# 基本检索
slm recall "查找关于 Python 项目的记忆"
# 带过滤条件
slm recall "查找 2024 年的项目" --profile work --tag project
# 限制返回数量
slm recall "查找相关文档" --top 5
```
### 8.2 API 检索
```python
# 资料来源：src/superlocalmemory/server/api.py
from fastapi import FastAPI
app = FastAPI()
@app.post("/api/recall")
async def recall_memories(request: SearchRequest):
"""
检索记忆条目
请求体:
query: str - 搜索查询
top_k: int - 返回数量
profile: str - 可选：限定 profile
tags: List[str] - 可选：标签过滤
"""
engine = get_retrieval_engine()
results = await engine.retrieve(
query=request.query,
top_k=request.top_k,
filters=request.filters
)
return {"memories": results}
```
### 8.3 MCP 工具检索
```json
{
"name": "slm-recall",
"description": "从本地记忆库检索相关信息",
"inputSchema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"top_k": {"type": "integer", "default": 5},
"profile": {"type": "string"}
}
}
}
```
## 9. 常见问题与故障排查
### 9.1 检索无响应
**问题**: 执行 `slm remember xxx` 后长时间无响应。
**原因分析**:
- 嵌入模型未下载完成
- Ollama 服务未启动（Mode B）
- 网络超时
**解决方案**:
1. 检查模型状态：`slm status`
2. 确保 Ollama 运行：`ollama serve`
3. 确认 v3.3.19+ 已安装
*资料来源*: [Issue #11](https://github.com/qualixar/superlocalmemory/issues/11)
### 9.2 Linux/Docker 环境问题
**问题**: 在 Docker 容器中检索失败。
**常见原因**:
- 内存不足导致嵌入模型加载失败
- 容器网络隔离阻止 Ollama 访问
- 路径权限问题
**解决方案**:
1. 增加 Docker 内存限制（建议 4GB+）
2. 使用 `--network=host` 或配置 Ollama 容器网络
3. 验证数据目录权限
*资料来源*: [Issue #26](https://github.com/qualixar/superlocalmemory/issues/26)
### 9.3 检索结果不准确
**排查步骤**:
1. 检查嵌入模型是否正确加载
2. 调整通道权重配置
3. 验证记忆条目的 importance 和 tags 标记
4. 考虑使用精确模式（`RetrievalMode.PRECISE`）
### 9.4 api_key 被忽略问题
**问题**: Mode B 配置下 API key 被静默丢弃。
**原因**: `config.py` 的 `for_mode()` 方法在 Mode B 分支未正确传递 `api_key`。
**状态**: 需确认修复版本。
*资料来源*: [Issue #9](https://github.com/qualixar/superlocalmemory/issues/9)
## 10. 性能优化建议
### 10.1 嵌入缓存
启用嵌入结果缓存以加速重复查询：
```python
# 资料来源：src/superlocalmemory/core/embeddings.py
class EmbeddingCache:
"""查询嵌入结果缓存"""
def __init__(self, max_size: int = 10000, ttl_seconds: int = 3600):
self.cache = LRUCache(max_size)
self.ttl = ttl_seconds
def get_or_compute(self, text: str, embed_func) -> np.ndarray:
cache_key = hash(text)
if cached := self.cache.get(cache_key):
return cached.value
embedding = embed_func(text)
self.cache.set(cache_key, embedding, expire=self.ttl)
return embedding
```
### 10.2 异步并行执行
```python
# 四通道并行执行
async def parallel_retrieve(query: str):
results = await asyncio.gather(
semantic_channel.retrieve(query),
hopfield_channel.retrieve(query),
spreading_activation.retrieve(query),
fisher_rao_channel.retrieve(query),
return_exceptions=True
)
return results
```
## 11. 相关文档
- [Home — 项目首页](../Home)
- [Universal Architecture — 系统架构](../Universal-Architecture)
- [MCP Integration — MCP 协议集成](../MCP-Integration)
- [Installation — 安装指南](../Installation)
- [FAQ — 常见问题](../FAQ)
---
**维护者**: Varun Pratap Bhardwaj
**项目主页**: [https://github.com/qualixar/superlocalmemory](https://github.com/qualixar/superlocalmemory)
**许可证**: AGPL-3.0-or-later
---
## 记忆生命周期
### 相关页面
相关主题：[V3 架构](#page-architecture), [检索管道](#page-retrieval-pipeline)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/core/consolidation_engine.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/consolidation_engine.py)
- [src/superlocalmemory/encoding/consolidator.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/encoding/consolidator.py)
- [src/superlocalmemory/encoding/cognitive_consolidator.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/encoding/cognitive_consolidator.py)
- [src/superlocalmemory/core/pruning_engine.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/pruning_engine.py)
- [src/superlocalmemory/core/tier_manager.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/tier_manager.py)
- [src/superlocalmemory/learning/adaptive.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/learning/adaptive.py)
- [src/superlocalmemory/learning/behavioral.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/learning/behavioral.py)
- [src/superlocalmemory/storage/models.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/storage/models.py)
# 记忆生命周期
本文档介绍 SuperLocalMemory 中的记忆生命周期管理系统，该系统使记忆能够根据使用模式自动组织自己，始终保持系统快速和相关。
## 概述
记忆生命周期是 SuperLocalMemory V2.8.0 引入的核心功能模块，负责管理记忆从创建到最终删除的完整演进过程。系统通过多层次的分析引擎，自动识别重要记忆、次要记忆和过时记忆，并执行相应的存储层迁移、合并和清理操作。
该系统解决了传统记忆系统的核心问题：当记忆数量增长到数千条时，系统性能下降，相关记忆的检索精度降低。生命周期管理通过智能化的组织策略，确保系统长期运行的稳定性和检索效率。
## 核心架构
### 生命周期组件关系
```mermaid
graph TD
A[记忆写入] --> B{访问频率分析}
B -->|高频| C[热点层 HOT]
B -->|中频| D[温层 WARM]
B -->|低频| E[冷层 COLD]
C --> F[合并引擎]
D --> F
E --> F
F --> G[修剪引擎]
G --> H[删除队列]
I[认知整合器] --> F
J[自适应学习器] --> B
K[行为学习器] --> J
```
### 记忆状态流转
```mermaid
stateDiagram-v2
[*] --> 新建: slm remember
新建 --> 活跃: 首次访问
活跃 --> 热点: 高频访问
活跃 --> 温热: 中频访问
活跃 --> 休眠: 低频访问
休眠 --> 活跃: 再次访问
休眠 --> 归档: 超时未访问
热点 --> 温热: 访问下降
温热 --> 冷层: 持续低频
冷层 --> 删除: 超过保留期
归档 --> 活跃: 需要召回
热点 --> 合并: 碎片整理
[*] --> 删除: 手动删除
```
## 核心组件
### 合并引擎 (Consolidation Engine)
合并引擎是生命周期管理的核心组件，负责识别可合并的关联记忆并生成高密度记忆表示。
```python
# 资料来源：src/superlocalmemory/core/consolidation_engine.py:1-50
class ConsolidationEngine:
"""信息几何合并引擎，支持4通道检索"""
```
**主要职责：**
| 功能 | 描述 |
|------|------|
| 主题签名计算 | 使用 `compute_topic_signature` 计算记忆主题特征 |
| 事实关联分析 | 识别同一主题下的多条相关记忆 |
| 向量合并 | 基于 Fisher-Rao 相似度合并高相关记忆 |
| 碎片整理 | 清理重复记忆，保持存储紧凑 |
**配置参数：**
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `consolidation_threshold` | 0.85 | 合并相似度阈值 |
| `max_facts_per_topic` | 50 | 每主题最大记忆数 |
| `consolidation_interval` | 3600 | 合并检查间隔（秒） |
### 认知整合器 (Cognitive Consolidator)
认知整合器实现高级记忆整合策略，模拟人类记忆的遗忘曲线和整合机制。
```python
# 资料来源：src/superlocalmemory/encoding/cognitive_consolidator.py:1-30
class CognitiveConsolidator:
"""认知整合器 - 模拟海马体整合机制"""
```
**整合阶段：**
1. **提取阶段** — 识别当前会话中的关键事实
2. **整合阶段** — 将新事实与已有记忆关联
3. **固化阶段** — 生成更紧凑的记忆表示
4. **索引更新** — 更新多通道检索索引
### 修剪引擎 (Pruning Engine)
修剪引擎负责识别和删除不再需要的记忆，释放存储空间。
```python
# 资料来源：src/superlocalmemory/core/pruning_engine.py:1-40
class PruningEngine:
"""智能修剪引擎 - 基于使用模式清理记忆"""
```
**修剪策略：**
| 策略 | 触发条件 | 行为 |
|------|----------|------|
| 访问频率 | 90天内无访问 | 移至冷层 |
| 重要性衰减 | 重要度持续降低 | 降低存储优先级 |
| 重复合并 | 相似度超过阈值 | 合并重复记忆 |
| 过期删除 | 超过保留期限 | 彻底删除 |
### 层管理器 (Tier Manager)
层管理器控制记忆在不同存储层之间的迁移。
```python
# 资料来源：src/superlocalmemory/core/tier_manager.py:1-60
class TierManager:
"""三层存储架构管理器"""
```
**存储层定义：**
| 层级 | 名称 | 访问延迟 | 存储成本 | 适用场景 |
|------|------|----------|----------|----------|
| HOT | 热点层 | < 1ms | 高 | 活跃会话、高频访问 |
| WARM | 温热层 | < 10ms | 中 | 最近使用、中频访问 |
| COLD | 冷层 | < 100ms | 低 | 历史记忆、低频访问 |
## 自适应学习
### 自适应学习器 (Adaptive Learner)
自适应学习器从用户使用模式中学习，优化记忆组织和检索优先级。
```python
# 资料来源：src/superlocalmemory/learning/adaptive.py:1-80
class AdaptiveLearner:
"""三层自适应学习：技术偏好、项目上下文、工作流模式"""
```
**学习层次：**
1. **技术偏好学习** — 识别用户偏好的编程语言、框架和工具
2. **项目上下文学习** — 理解当前项目的技术栈和架构
3. **工作流模式学习** — 掌握用户的常规操作序列和习惯
### 行为学习器 (Behavioral Learner)
行为学习器从操作结果中学习，实现零 LLM 推理的本地模式识别。
```python
# 资料来源：src/superlocalmemory/learning/behavioral.py:1-100
class BehavioralLearner:
"""行为学习器 - 从操作结果中学习"""
```
**学习机制：**
- 追踪记忆召回后的用户反馈（采纳、修改、忽略）
- 分析成功检索与失败检索的模式差异
- 跨项目迁移有效的学习策略
- 无需 LLM 推理，完全基于本地模式识别
## 存储模型
### 记忆数据模型
```python
# 资料来源：src/superlocalmemory/storage/models.py:50-120
class MemoryModel:
"""记忆存储模型"""
fields = [
"id", # 唯一标识符
"content", # 记忆内容
"embedding", # 向量表示
"topic", # 主题分类
"tier", # 存储层级
"access_count", # 访问计数
"last_access", # 最后访问时间
"created_at", # 创建时间
"importance", # 重要性评分
"tags", # 标签系统
]
```
### 生命周期元数据
| 字段 | 类型 | 说明 |
|------|------|------|
| `lifecycle_state` | string | 当前生命周期状态 |
| `consolidation_count` | int | 被合并次数 |
| `pruning_score` | float | 修剪优先级评分 |
| `learned_weights` | dict | 学习到的权重参数 |
## 使用方法
### CLI 命令
```bash
# 查看记忆生命周期状态
slm status --lifecycle
# 手动触发合并操作
slm lifecycle consolidate
# 查看存储层分布
slm tier list
# 强制修剪低价值记忆
slm lifecycle prune --dry-run
# 导出生命周期报告
slm lifecycle report --format json
```
### API 端点
```bash
# 获取记忆层级信息
GET /api/v3/lifecycle/tiers
# 触发合并检查
POST /api/v3/lifecycle/consolidate
# 获取修剪建议
GET /api/v3/lifecycle/pruning-candidates?threshold=0.3
# 更新记忆保留策略
PUT /api/v3/lifecycle/policy
```
## 配置选项
### 全局配置
```yaml
# ~/.superlocalmemory/config.yaml
lifecycle:
enabled: true
consolidation:
enabled: true
interval_seconds: 3600
similarity_threshold: 0.85
max_batch_size: 100
pruning:
enabled: true
retention_days: 365
min_importance: 0.1
min_access_count: 0
tiering:
hot_threshold_accesses: 100
warm_threshold_accesses: 10
cold_threshold_days: 90
```
### 环境变量
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SLM_LIFECYCLE_ENABLED` | `true` | 启用生命周期管理 |
| `SLM_CONSOLIDATION_INTERVAL` | `3600` | 合并检查间隔（秒） |
| `SLM_PRUNING_RETENTION_DAYS` | `365` | 记忆保留天数 |
| `SLM_TIER_HOT_THRESHOLD` | `100` | 热点层访问阈值 |
## 常见问题
### Linux/Docker 环境下的认知整合问题
用户在 Linux 或 Docker 容器环境中报告了认知整合和追踪相关的问题。这些问题通常与容器资源限制或 cgroup 隔离相关。
**解决方案：**
1. 确保容器分配足够的内存资源
2. 检查 `/sys/fs/cgroup` 是否正确挂载
3. 对于大规模记忆库，考虑使用主机网络模式
```bash
# 推荐 Docker 配置
docker run --memory=4g --memory-swap=4g \
--cgroupns=host \
-v ~/.superlocalmemory:/root/.superlocalmemory \
your-slm-image
```
### 合并操作耗时过长
当记忆数量达到数千条时，合并操作可能需要较长时间。系统提供了增量合并策略。
```bash
# 使用增量模式（每次只处理有限数量）
slm lifecycle consolidate --incremental --batch-size=50
```
### 记忆层级自动迁移不生效
如果记忆未按预期迁移到正确的层级，请检查：
1. `SLM_DATA_DIR` 环境变量是否正确设置（当前版本支持）
2. 访问统计是否正常记录
3. 时间同步是否正确
## 与其他系统的集成
### 行为学习与检索系统
行为学习器的输出直接影响 4 通道检索的权重分配：
```mermaid
graph LR
A[行为学习] --> B[重要性权重]
A --> C[上下文权重]
B --> D[4通道检索]
C --> D
D --> E[检索结果排序]
```
### 企业合规集成
记忆生命周期与合规模块协同工作：
- **访问审计** — 所有层级迁移都有完整日志
- **保留策略** — 符合 EU AI Act 等法规要求
- **数据导出** — 支持完整生命周期数据的导出
## See Also
- [Home](Home) — 主页和功能概览
- [Universal-Architecture](Universal-Architecture) — 7层系统架构
- [Installation](Installation) — 安装和配置指南
- [MCP-Integration](MCP-Integration) — MCP 协议集成
- [Universal-Skills](Universal-Skills) — 通用技能命令
---
**创建者：** Varun Pratap Bhardwaj
**项目主页：** [https://github.com/qualixar/superlocalmemory](https://github.com/qualixar/superlocalmemory)
**许可证：** AGPL-3.0-or-later
---
## 多机 Mesh 网络
### 相关页面
相关主题：[配置参考](#page-configuration), [MCP 工具集](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/server/unified_daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
- [src/superlocalmemory/server/ui.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
- [src/superlocalmemory/server/api.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/api.py)
- [src/superlocalmemory/cli/setup_wizard.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
- [src/superlocalmemory/cli/main.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
- [ide/integrations/llamaindex/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/llamaindex/README.md)
- [ide/integrations/langchain/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/langchain/README.md)
- [wiki-content/v2-archive/README.md](https://github.com/qualixar/superlocalmemory/blob/main/wiki-content/v2-archive/README.md)
# 多机 Mesh 网络
SuperLocalMemory 多机 Mesh 网络功能允许在多个物理机器或虚拟机之间建立分布式记忆同步。通过集成 slm-mesh 组件，系统支持在家庭实验室或企业内网环境中跨节点共享和管理记忆数据。
## 功能概述
SuperLocalMemory 的多机 Mesh 网络基于点对点（Peer-to-Peer）架构设计，旨在实现跨机器的记忆同步和共享。每个节点既可以是记忆的消费者，也可以是记忆的生产者，所有数据交互通过加密通道进行，确保数据隐私和安全。
当前实现中，SLM 守护进程默认绑定 `127.0.0.1`，这限制了系统在多机环境中的使用。社区用户报告指出，在运行 7 台机器的 WireGuard mesh 网络环境中，这一限制成为主要瓶颈。资料来源：[GitHub Issue #23](https://github.com/qualixar/superlocalmemory/issues/23)
## 架构设计
### 网络拓扑
SuperLocalMemory Mesh 网络采用混合拓扑结构，结合星型拓扑的易管理性和网状拓扑的高可靠性特点。每个节点维护与其他节点的连接状态，并能够动态发现和加入网络。
```mermaid
graph TD
A[节点 A
192.168.1.10] <--> B[节点 B
192.168.1.11]
A <--> C[节点 C
192.168.1.12]
B <--> D[节点 D
192.168.1.13]
C <--> D
B <--> C
subgraph WireGuard Mesh
A
B
C
D
end
E[记忆数据库
SQLite] --> A
F[记忆数据库
SQLite] --> B
G[记忆数据库
SQLite] --> C
H[记忆数据库
SQLite] --> D
```
### 核心组件
| 组件名称 | 类型 | 功能描述 | 源码位置 |
|---------|------|----------|----------|
| Mesh Broker | 服务进程 | 管理节点间连接和消息路由 | `src/superlocalmemory/mesh/broker.py` |
| Remote Sync | 同步模块 | 处理跨节点记忆同步 | `src/superlocalmemory/mesh/remote_sync.py` |
| Mesh Tools | MCP 工具 | 提供 MCP 协议接口 | `src/superlocalmemory/mcp/tools_mesh.py` |
资料来源：[wiki-content/v2-archive/README.md](https://github.com/qualixar/superlocalmemory/blob/main/wiki-content/v2-archive/README.md)
## 配置指南
### 环境变量配置
SuperLocalMemory 支持通过环境变量配置数据目录和绑定地址。在多机部署场景下，配置 `SL_MEMORY_PATH` 可指定非默认数据存储位置：
```bash
# 设置自定义数据目录
export SL_MEMORY_PATH="/mnt/shared/slm-data"
# 设置监听地址（需要支持可配置绑定）
export SLM_HOST="0.0.0.0"
```
资料来源：[src/superlocalmemory/cli/setup_wizard.py:34](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
### 守护进程配置
守护进程通过 `unified_daemon.py` 统一管理服务生命周期。在多机环境中，守护进程需要配置为监听所有可用网络接口：
```python
# S9-SKEP-15: 版本标记在迁移块成功后才写入
_want_write_marker = _prev != _slm_version
if _want_write_marker:
if _prev is None:
logger.info(
"[slm] first boot on v%s — run `slm status` to see your "
"memory overview. Changelog: "
"https://github.com/qualixar/superlocalmemory/blob/main/CHANGELOG.md",
_slm_version,
)
```
资料来源：[src/superlocalmemory/server/unified_daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
## WebSocket 实时通信
SuperLocalMemory V3 实现了基于 WebSocket 的实时通信机制，支持多客户端同时连接和数据推送。服务端通过 `ws_manager` 管理所有活跃连接：
```python
# Wire WebSocket manager into routes that need broadcast capability
import superlocalmemory.server.routes.profiles as _profiles_mod
import superlocalmemory.server.routes.data_io as _data_io_mod
_profiles_mod.ws_manager = ws_manager
_data_io_mod.ws_manager = ws_manager
```
资料来源：[src/superlocalmemory/server/ui.py:98-102](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
### CORS 配置
多机环境中，WebSocket 连接需要正确配置跨域资源共享：
```python
application.add_middleware(
CORSMiddleware,
allow_origins=[
"http://localhost:8765", "http://127.0.0.1:8765",
"http://localhost:8417", "http://127.0.0.1:8417",
],
allow_credentials=True,
allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
allow_headers=["Content-Type", "Authorization", "X-SLM-API-Key"],
)
```
资料来源：[src/superlocalmemory/server/ui.py:55-62](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
## API 服务端点
FastAPI 服务提供了完整的 REST API 接口，支持多机环境下的记忆查询和管理操作：
```python
class SearchRequest(BaseModel):
query: str
```
资料来源：[src/superlocalmemory/server/api.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/api.py)
### 主要路由模块
| 路由模块 | 功能 | 用途 |
|---------|------|------|
| memories_router | 记忆 CRUD | 创建、读取、更新、删除记忆 |
| stats_router | 统计信息 | 获取系统运行统计 |
| profiles_router | 配置文件 | 管理用户配置文件 |
| backup_router | 备份管理 | 备份和恢复记忆数据 |
| events_router | 事件追踪 | 记录和查询系统事件 |
| agents_router | 代理管理 | 管理 AI 代理配置 |
资料来源：[src/superlocalmemory/server/ui.py:71-79](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
## 使用场景
### 家庭实验室多机部署
在家庭实验室环境中，用户可以部署多台运行 SuperLocalMemory 的机器，通过 WireGuard VPN 连接形成私有 mesh 网络。每台机器运行独立的记忆实例，同时可以共享部分记忆给其他节点。
典型配置包括 7 台机器的部署，通过 WireGuard mesh 实现全网格连接。资料来源：[GitHub Issue #23](https://github.com/qualixar/superlocalmemory/issues/23)
### AI 代理团队协作
多个专业化的 AI 代理可以分别运行在不同的机器上，通过 Mesh 网络共享知识库。每个代理维护私有记忆，同时可以访问团队共享的全局记忆。
```mermaid
graph LR
subgraph 个人记忆
P1[代理 1 私有]
P2[代理 2 私有]
P3[代理 3 私有]
end
subgraph 共享记忆
G1[团队知识库]
G2[项目文档]
G3[通用技能]
end
P1 <--> G1
P2 <--> G1
P3 <--> G1
P1 <--> G2
P2 <--> G2
P3 <--> G3
```
资料来源：[GitHub Issue #20](https://github.com/qualixar/superlocalmemory/issues/20)
## 第三方集成
### LlamaIndex 集成
SuperLocalMemory 支持作为 LlamaIndex 的聊天存储后端使用。在多机环境中，可以配置自定义数据库路径实现跨节点共享：
```python
# 使用自定义数据库文件实现多机共享
chat_store = SuperLocalMemoryChatStore(
db_path="/path/to/shared/memory.db"
)
```
- **内容**: JSON 序列化的消息数据
- **标签**: `llamaindex:chat:` 用于会话隔离
- **项目**: `llamaindex` 用于标识
- **重要性**: 3（较低，聊天消息不会干扰搜索结果）
资料来源：[ide/integrations/llamaindex/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/llamaindex/README.md)
### LangChain 集成
LangChain 用户同样可以使用 SuperLocalMemory 作为消息历史存储后端：
```python
from langchain_superlocalmemory import SuperLocalMemoryChatMessageHistory
# 跨节点共享对话历史
history = SuperLocalMemoryChatMessageHistory(
session_id="my-session",
db_path="/path/to/shared/memory.db",
)
```
资料来源：[ide/integrations/langchain/README.md](https://github.com/qualixar/superlocalmemory/blob/main/ide/integrations/langchain/README.md)
## 常见问题
### 绑定地址限制
**问题**: SLM 守护进程和 slm-mesh broker 硬编码绑定 `127.0.0.1`，无法接受外部连接。
**解决方案**: 社区正在开发 `SLM_HOST` 功能以支持可配置的绑定地址。在生产环境中，可以考虑使用反向代理（如 nginx）将外部请求转发到本地服务。
资料来源：[GitHub Issue #23](https://github.com/qualixar/superlocalmemory/issues/23)
### Docker 容器中的网络问题
**问题**: 在 Docker 容器中运行 SuperLocalMemory 时可能出现认知整合和追踪问题。
**环境信息**:
- Ubuntu/Debian Docker 容器
- Python 3.12
- Ollama 提供服务
**排查建议**:
1. 检查容器网络模式配置
2. 确保端口映射正确
3. 验证 Ollama 服务可达性
资料来源：[GitHub Issue #26](https://github.com/qualixar/superlocalmemory/issues/26)
### 数据目录配置未生效
**问题**: `SLM_DATA_DIR` 环境变量在某些版本中未被正确使用。
**临时解决方案**: 使用 `SL_MEMORY_PATH` 环境变量替代：
```bash
export SL_MEMORY_PATH="/自定义/路径"
```
资料来源：[GitHub Issue #10](https://github.com/qualixar/superlocalmemory/issues/10)
## 版本历史
| 版本 | 发布日期 | 多机网络相关更新 |
|------|----------|------------------|
| v2.8.0 | 2024 | 企业合规性支持、记忆生命周期管理 |
| v2.7.0 | 2024 | 行为学习、跨项目知识转移 |
| v2.6.0 | 2024 | 安全加固、配置文件隔离 |
| v3.4.58 | 当前 | V3 引擎、WebSocket 实时通信 |
资料来源：[CHANGELOG.md](https://github.com/qualixar/superlocalmemory/blob/main/CHANGELOG.md)
## 命令行接口
多机部署场景下常用的 CLI 命令：
```bash
# 启动守护进程（自动检测并启动）
slm status
# 检查系统状态
slm status
# 切换配置文件
slm switch-profile
# 列出最近记忆
slm list-recent
# 查看网络连接状态
slm recall "network status"
```
资料来源：[src/superlocalmemory/cli/main.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
### 自动启动机制
V3.4.4 引入了守护进程自动启动机制，确保多机环境中的服务可用性：
```python
_NO_DAEMON_COMMANDS = {
"setup", "mode", "provider", "connect", "migrate", "mcp", "warmup",
"config", "evolve", "db",
"disable", "enable", "clear-cache", "reconfigure", "benchmark",
"rotate-token",
}
```
资料来源：[src/superlocalmemory/cli/main.py:56-61](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/main.py)
## 后续发展
多机 Mesh 网络功能正在积极开发中，未来版本计划支持：
- **多作用域记忆**: 个人、全局、共享作用域及作用域感知检索
- **可配置嵌入端点**: 支持 OpenAI 兼容 API 的本地嵌入服务
- **增强的跨节点同步**: 更高效的增量同步机制
资料来源：[GitHub Issue #20](https://github.com/qualixar/superlocalmemory/issues/20)、[GitHub Issue #16](https://github.com/qualixar/superlocalmemory/issues/16)
## 相关链接
- [官方文档](https://superlocalmemory.com)
- [安装指南](./Installation)
- [架构说明](./Universal-Architecture)
- [MCP 集成](./MCP-Integration)
- [常见问题](./FAQ)
- [GitHub 问题反馈](https://github.com/qualixar/superlocalmemory/issues)
- [更新日志](https://github.com/qualixar/superlocalmemory/blob/main/CHANGELOG.md)
---
**维护者**: Varun Pratap Bhardwaj
**项目主页**: [https://github.com/qualixar/superlocalmemory](https://github.com/qualixar/superlocalmemory)
**许可证**: AGPL-3.0-or-later
---
## 配置参考
### 相关页面
相关主题：[快速入门](#page-getting-started), [三种运行模式详解](#page-modes)
相关源码文件
以下源码文件用于生成本页说明：
- [src/superlocalmemory/core/config.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/core/config.py)
- [src/superlocalmemory/server/api.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/api.py)
- [src/superlocalmemory/server/ui.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/ui.py)
- [src/superlocalmemory/server/unified_daemon.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/server/unified_daemon.py)
- [src/superlocalmemory/cli/setup_wizard.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/cli/setup_wizard.py)
- [src/superlocalmemory/storage/database.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/storage/database.py)
- [src/superlocalmemory/storage/v2_migrator.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/storage/v2_migrator.py)
- [src/superlocalmemory/infra/rate_limiter.py](https://github.com/qualixar/superlocalmemory/blob/main/src/superlocalmemory/infra/rate_limiter.py)
# 配置参考
本文档提供 SuperLocalMemory V3 配置系统的完整参考，包括配置文件的结构、环境变量、各模式配置、API 配置以及常见问题排查。
## 概述
SuperLocalMemory V3 采用 YAML 配置文件配合环境变量的双重配置机制。系统支持两种运行模式：
- **Mode A**：零 LLM 推理模式，使用 Fisher-Rao 度量进行纯数学相似度计算
- **Mode B**：使用 LLM 进行语义理解和推理
配置文件位于 `~/.superlocalmemory/config.yaml`，首次运行时会通过设置向导自动生成。
资料来源：[src/superlocalmemory/core/config.py:1-100]()
## 配置架构
```mermaid
graph TD
A[用户配置] --> B[环境变量]
A --> C[YAML 配置文件]
B --> D[配置加载优先级]
C --> D
D --> E[SLMConfig 对象]
E --> F[Mode A 配置]
E --> G[Mode B 配置]
E --> H[API Server 配置]
E --> I[数据库配置]
```
### 配置加载流程
1. 系统首先检测环境变量 `SL_MEMORY_PATH`
2. 如果未设置，默认使用 `~/.superlocalmemory/`
3. 加载 `config.yaml` 文件
4. 根据配置的 `mode` 选择对应的配置分支
资料来源：[src/superlocalmemory/core/config.py:50-80]()
## 环境变量
SuperLocalMemory V3 支持以下环境变量：
| 环境变量 | 说明 | 默认值 | 示例 |
|---------|------|--------|------|
| `SL_MEMORY_PATH` | 数据目录路径 | `~/.superlocalmemory/` | `/opt/slm/data/` |
| `SLM_NON_INTERACTIVE` | 禁用交互式提示 | `false` | `1` |
| `CI` | CI 环境标志 | - | `true` |
### SL_MEMORY_PATH
设置自定义数据目录，所有数据库文件和配置文件将存储在此目录下。
```bash
# Linux/macOS
export SL_MEMORY_PATH=/opt/superlocalmemory
# Windows
set SL_MEMORY_PATH=C:\Data\slm
```
> ⚠️ 注意：社区反馈显示 `SLM_DATA_DIR` 环境变量在某些版本中未被正确实现。推荐使用 `SL_MEMORY_PATH`。
资料来源：[src/superlocalmemory/cli/setup_wizard.py:30-35]()
### SLM_NON_INTERACTIVE
在脚本或容器环境中禁用交互式提示，自动使用默认值。
```bash
SLM_NON_INTERACTIVE=1 slm setup
```
## 配置文件结构
完整的 `config.yaml` 结构如下：
```yaml
# 基础配置
version: "3.4"
mode: "a" # a: Mode A, b: Mode B
# Mode A 配置（零 LLM 模式）
mode_a:
embedding_model: "nomic-ai/nomic-embed-text-v1.5"
reranker_model: "cross-encoder/ms-marco-MiniLM-L-12-v2"
# Mode B 配置（LLM 模式）
mode_b:
provider: "ollama" # ollama, openai, anthropic 等
model: "llama3.2"
api_base: "http://localhost:11434"
api_key: "" # OpenAI 兼容 API 密钥
# 记忆配置
memory:
default_importance: 5
auto_consolidate: true
consolidation_threshold: 100
# API 服务器配置
api:
host: "127.0.0.1"
port: 8765
rate_limit:
read: 120 # 每分钟请求数
write: 30
cors_origins:
- "http://localhost:8765"
- "http://127.0.0.1:8765"
```
资料来源：[src/superlocalmemory/core/config.py:100-150]()
## 模式配置详解
### Mode A（零 LLM 模式）
Mode A 不依赖任何外部 LLM API，使用纯数学方法进行记忆检索：
```yaml
mode: "a"
mode_a:
# 向量嵌入模型（HuggingFace 格式）
embedding_model: "nomic-ai/nomic-embed-text-v1.5"
# 重排序模型
reranker_model: "cross-encoder/ms-marco-MiniLM-L-12-v2"
```
**特点**：
- 完全离线运行，无需 API 密钥
- 使用 Fisher-Rao 度量进行相似度计算
- 资源占用较低
- 适合隐私敏感场景
> ⚠️ 社区问题：在某些 Linux/Docker 环境下，Mode A 的认知整合功能可能出现响应延迟。参见 [Issue #26](https://github.com/qualixar/superlocalmemory/issues/26)。
资料来源：[src/superlocalmemory/core/config.py:80-100]()
### Mode B（LLM 模式）
Mode B 使用 LLM 进行语义理解和推理：
```yaml
mode: "b"
mode_b:
provider: "ollama" # 支持: ollama, openai, anthropic, localai
model: "llama3.2"
api_base: "http://localhost:11434"
api_key: "" # 非 Ollama 提供商需要
```
**支持的提供商**：
| 提供商 | api_base 示例 | 需要 api_key |
|-------|---------------|-------------|
| ollama | `http://localhost:11434` | 否 |
| openai | `https://api.openai.com/v1` | 是 |
| anthropic | `https://api.anthropic.com` | 是 |
| localai | `http://localhost:8080` | 可选 |
> ⚠️ **已知问题**：`api_key` 在 Mode B 配置中可能被静默丢弃，导致 `LLMBackbone.is_available()` 返回 `False`。参见 [Issue #9](https://github.com/qualixar/superlocalmemory/issues/9)。
资料来源：[src/superlocalmemory/core/config.py:100-130]()
### 向量模型配置
Mode B 支持自定义嵌入端点：
```yaml
mode_b:
provider: "openai"
embedding_provider: "openai"
embedding_model: "text-embedding-3-small"
embedding_api_base: "https://api.openai.com/v1"
```
> 💡 **功能请求**：社区请求支持 OpenAI 兼容的本地嵌入端点以提升非英语语言的潜在支持。参见 [Issue #16](https://github.com/qualixar/superlocalmemory/issues/16)。
## API 服务器配置
API 服务器负责提供 REST API 和 WebSocket 接口：
```yaml
api:
host: "127.0.0.1" # 绑定地址
port: 8765
# 速率限制
rate_limit:
read: 120 # 读操作：每分钟 120 次
write: 30 # 写操作：每分钟 30 次
# CORS 允许的来源
cors_origins:
- "http://localhost:8765"
- "http://127.0.0.1:8765"
- "http://localhost:8417"
```
### 绑定地址配置
当前版本中，API 服务器默认绑定到 `127.0.0.1`。
> ⚠️ **限制**：社区请求支持配置 `SLM_HOST` 环境变量以允许非本地绑定，但当前版本尚未实现。参见 [Issue #23](https://github.com/qualixar/superlocalmemory/issues/23)。
### 速率限制
```yaml
api:
rate_limit:
read: 120 # 读操作速率限制
write: 30 # 写操作速率限制
```
实现代码位于 `superlocalmemory.infra.rate_limiter.RateLimiter`：
```python
_write_limiter = RateLimiter(max_requests=30, window_seconds=60)
_read_limiter = RateLimiter(max_requests=120, window_seconds=60)
```
资料来源：[src/superlocalmemory/server/ui.py:30-50]()
## 数据库配置
数据库使用 SQLite，路径由环境变量或默认路径决定：
```python
MEMORY_DIR = Path.home() / ".superlocalmemory"
DB_PATH = MEMORY_DIR / "memory.db"
```
### 数据目录结构
```
~/.superlocalmemory/
├── config.yaml # 配置文件
├── memory.db # SQLite 数据库
├── .setup-complete # 设置完成标记
├── learning/ # 学习数据目录
└── backups/ # 自动备份目录
```
### V2 数据迁移
如果检测到 V2 安装，会自动提示迁移：
```python
from superlocalmemory.storage.v2_migrator import V2Migrator
migrator = V2Migrator()
if migrator.detect_v2() and not migrator.is_already_migrated():
# 执行迁移
```
资料来源：[src/superlocalmemory/storage/v2_migrator.py:1-50]()
## 初始化向导
首次运行时，系统自动调用设置向导：
```bash
slm setup
```
### 向导流程
```mermaid
graph TD
A[检测交互模式] --> B{是否为交互式?}
B -->|是| C[显示欢迎信息]
B -->|否| D[使用默认配置]
C --> E[下载模型]
E --> F[验证安装]
F --> G[创建配置文件]
G --> H[设置完成标记]
D --> H
```
### 非交互模式
```bash
SLM_NON_INTERACTIVE=1 slm setup
```
资料来源：[src/superlocalmemory/cli/setup_wizard.py:50-100]()
## 常见配置问题
### 问题：配置未生效
**原因**：配置文件格式错误或权限问题
**解决方案**：
1. 检查 `~/.superlocalmemory/config.yaml` 是否存在
2. 验证 YAML 语法
3. 确保文件可读
```bash
cat ~/.superlocalmemory/config.yaml
```
### 问题：Mode B LLM 不可用
**原因**：`api_key` 未正确传递
**解决方案**：
1. 检查 `config.yaml` 中 `mode_b.api_key` 是否设置
2. 验证 LLM 服务是否运行
3. 确认 `api_base` 配置正确
```bash
slm status
```
### 问题：数据库锁定
**原因**：多个进程同时访问数据库
**解决方案**：
1. 确保只有一个 `slmd` 守护进程运行
2. 检查是否有僵尸进程
```bash
pkill -f slmd
slm daemon
```
### 问题：Docker 容器中响应慢
**原因**：容器资源限制或模型加载延迟
参见 [Issue #26](https://github.com/qualixar/superlocalmemory/issues/26) 获取详细排查指南。
## 配置验证
使用 `slm status` 命令验证配置：
```bash
slm status
```
输出示例：
```
SuperLocalMemory V3.4.58
=======================
Mode: A
Embedding: nomic-ai/nomic-embed-text-v1.5
Database: ~/.superlocalmemory/memory.db
API Server: http://127.0.0.1:8765
```
## 相关文档
- [快速入门指南](./Quick-Start)
- [架构设计](./Universal-Architecture)
- [API 参考](./API-Reference)
- [MCP 集成](./MCP-Integration)
---
**作者**：Varun Pratap Bhardwaj
**项目**：https://github.com/qualixar/superlocalmemory
**文档版本**：3.4.58
---
---
## Doramagic 踩坑日志
项目：qualixar/superlocalmemory
摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Cognitive consolidation and trace issues on Linux/Docker setup。
## 1. 安装坑 · 来源证据：Cognitive consolidation and trace issues on Linux/Docker setup
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Cognitive consolidation and trace issues on Linux/Docker setup
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8628e403827148fcb5f3b537c1af2263 | https://github.com/qualixar/superlocalmemory/issues/26 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：GitHub issue body — qualixar SLM_HOST feature request
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GitHub issue body — qualixar SLM_HOST feature request
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c74d27ed1bf2462585e76845639adfd5 | https://github.com/qualixar/superlocalmemory/issues/23 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ba05e614f5a8499da175aa7ba09ac343 | https://github.com/qualixar/superlocalmemory/issues/20 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | host_targets=mcp_host, claude, claude_code, cursor, chatgpt
## 5. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | README/documentation is current enough for a first validation pass.
## 6. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | last_activity_observed missing
## 7. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | no_demo; severity=medium
## 8. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | no_demo; severity=medium
## 9. 安全/权限坑 · 来源证据：Can't clone on Windows- repo contains bin
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Can't clone on Windows- repo contains bin
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_be8654b4ef434c37bedf0a453e65f5d6 | https://github.com/qualixar/superlocalmemory/issues/7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 10. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | issue_or_pr_quality=unknown
## 11. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1150546081 | https://github.com/qualixar/superlocalmemory | release_recency=unknown