项目概述

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

核心架构

SuperLocalMemory 采用分层架构设计，包含七个核心层次，从数据存储到用户界面的完整技术栈。

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

架构层级说明

资料来源：src/superlocalmemory/server/api.py

两种运行模式

SuperLocalMemory 支持两种运行模式，适用于不同的使用场景和隐私需求。

Mode A：零 LLM 模式

纯本地计算模式，不依赖任何外部 LLM API。所有记忆检索基于 Fisher-Rao 相似度和四通道检索算法实现。

适用场景：

• 高度敏感的数据环境
• 无网络连接的离线环境
• 追求最快响应速度的场景

# Mode A 配置示例
config = SLMConfig.for_mode("A")

Mode B：LLM 增强模式

利用外部 LLM（如 Ollama、OpenAI 兼容 API）增强记忆理解能力。支持可配置的 API 端点和自定义模型。

适用场景：

• 需要更深层语义理解的场景
• 复杂对话上下文处理
• 非英语语言的语义检索

# Mode B 配置示例
config = SLMConfig.for_mode("B", provider="ollama", model="llama3")

资料来源：src/superlocalmemory/core/config.py

安装与快速开始

系统要求

安装方式

通过 npm 全局安装（推荐）：

npm install -g superlocalmemory

通过 pip 安装：

pip install superlocalmemory

安装完成后，运行 slm setup 启动交互式配置向导，系统会自动下载嵌入模型并完成初始配置。

资料来源：package.json

命令行接口

SuperLocalMemory 提供完整的命令行工具，支持所有核心操作。

recall 命令选项

slm recall "查询内容" [选项]

资料来源：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 工具列表

资料来源：wiki-content/v2-archive/README.md

LangChain 和 LlamaIndex 集成

SuperLocalMemory 提供与主流 AI 框架的原生集成，扩展其使用场景。

LangChain 集成

通过 langchain-superlocalmemory 包，将 SuperLocalMemory 作为 LangChain 的聊天历史存储后端。

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

LlamaIndex 集成

通过 llama-index-storage-chat-store-superlocalmemory 包，LlamaIndex 应用可使用 SuperLocalMemory 作为聊天存储。

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

Web UI 和 API 服务

SuperLocalMemory 提供基于 FastAPI 的 Web 服务，支持 REST API 和 WebSocket 实时通信。

服务启动

slm serve

服务默认在 http://localhost:8765 运行，支持以下端点：

聊天 SSE 接口

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

数据目录与环境变量

SuperLocalMemory 使用本地文件系统存储所有数据，默认位置为 ~/.superlocalmemory/。

目录结构

~/.superlocalmemory/
├── memory.db          # 主数据库（SQLite）
├── config.yaml       # 配置文件
├── .setup-complete   # 设置完成标记
└── ui/               # Web UI 资源

环境变量

资料来源：src/superlocalmemory/cli/setup_wizard.py

常见问题与已知问题

Docker/Linux 环境问题

在 Docker 或 Linux 环境中运行时，部分用户报告认知整合和追踪问题。确保容器内正确配置了 Python 3.9+ 和必要的系统依赖。

相关 Issue：#26

SLM_HOST 功能请求

当前版本中，守护进程和 mesh broker 将绑定地址硬编码为 127.0.0.1。对于需要在多机器集群（如 WireGuard mesh）环境中使用的用户，建议通过环境变量配置自定义主机地址。

相关 Issue：#23

非英语语言支持

Mode B 支持配置本地嵌入端点（如 OpenAI 兼容 API），以解锁非英语语言的语义检索能力。配置方法：

config = SLMConfig.for_mode(
    "B",
    embedding_endpoint="http://localhost:11434/api/embeddings"
)

相关 Issue：#16

版本历史与特性演进

资料来源：package.json

安全与合规

SuperLocalMemory V2.6.0 及更高版本包含全面的安全加固：

• 配置文件隔离：所有查询端点实现记忆隔离，防止跨配置泄露
• 信任评分系统：基于 Fisher-Rao 信息几何学的可信度评估
• 不可变审计日志：完整的访问和操作审计追踪
• EU AI Act 合规：满足欧盟人工智能法案要求

资料来源：src/superlocalmemory/server/ui.py

技术支持与参与

• 问题反馈：GitHub Issues
• 功能请求：GitHub Discussions
• 官方网站：superlocalmemory.com
• 开发者：Varun Pratap Bhardwaj

另请参阅

• Universal Architecture（通用架构） — 七层架构详解
• MCP Integration（MCP 集成） — 完整的 MCP 设置指南
• Universal Skills（通用技能） — 六种通用命令文档
• Installation（安装指南） — 详细安装说明
• FAQ（常见问题） — 常见问题解答

快速入门

SuperLocalMemory 是一款本地优先的 AI 记忆系统，采用信息几何学方法实现记忆存储与检索。本页面将引导您完成从安装到首次使用的完整流程，帮助您在数分钟内启动并运行 SuperLocalMemory。

概述

V3 架构的核心设计理念是零 LLM 推理的本地模式（Zero-LLM Mode），同时支持 EU AI Act 合规性要求。系统采用四通道检索机制，结合 Fisher-Rao 相似度进行信息几何学度量，实现精确的记忆召回。

资料来源：docs/ARCHITECTURE.md:1-50

核心特性

系统架构图

graph TD
    subgraph "客户端层"
        CLI[CLI 命令行]
        MCP[MCP 协议]
        REST[REST API]
        WS[WebSocket]
    end

    subgraph "服务层"
        Daemon[统一守护进程<br/>unified_daemon.py]
        API[FastAPI 服务器<br/>api.py]
        UI[UI 服务器<br/>ui.py]
    end

    subgraph "核心引擎层"
        Engine[MemoryEngine<br/>core/engine.py]
        Orchestrator[BackendOrchestrator<br/>backend_orchestrator.py]
    end

    subgraph "检索管道层"
        Semantic[语义通道]
        BM25[BM25 通道]
        Entity[实体通道]
        Temporal[时间通道]
        Hopfield[Hopfield 通道]
        Fusion[融合模块]
        Reranker[重排器]
    end

    subgraph "数学模块层"
        Fisher[Fisher-Rao 距离<br/>math/fisher.py]
        Riemannian[黎曼几何工具]
    end

    subgraph "存储层"
        SQLite[(SQLite<br/>memory.db)]
        Cache[上下文缓存<br/>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

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

通道详解

检索流程图

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

融合策略

重排器

重排器使用 cross-encoder 模型对候选记忆进行二次排序，提高最终结果的相关性。

资料来源：src/superlocalmemory/retrieval/reranker.py:1-60

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

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

UI 服务器

UI 服务器提供 Web 界面访问，运行在独立端口上。

资料来源：src/superlocalmemory/server/ui.py:1-120

• 默认端口: 8765 或 8417
• CORS 配置: 仅允许 localhost 访问
• 中间件: GZip 压缩、安全头、CORS

配置与模式

运行模式

环境变量

⚠️ 社区问题: Issue #10 指出 SLM_DATA_DIR 虽然有文档说明但实际未被使用，Issue #23 报告 SLM_HOST 硬编码为 127.0.0.1，在多机器部署场景下存在限制。

安装向导

首次启动时，系统会运行交互式安装向导，下载必要的嵌入模型。

资料来源：src/superlocalmemory/cli/setup_wizard.py:1-100

# 默认嵌入模型
_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 数据库中。

版本信息

相关文档

• 安装指南
• MCP 集成
• 通用技能
• 常见问题
• CHANGELOG

模式概述

SuperLocalMemory 的三种运行模式是系统的核心架构设计，它们决定了记忆系统的检索方式、依赖组件和性能特征：

资料来源：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

配置方法

# 切换到 Mode A（零LLM模式）
slm mode a

# 验证当前模式
slm status

配置文件位于 ~/.superlocalmemory/config.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

配置示例

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：

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 功能不可用：

# 问题代码位置
# src/superlocalmemory/core/config.py — SLMConfig.for_mode(), Mode B 分支

临时解决方案：

1. 确认 api_key 已正确写入配置文件
2. 检查 API 端点可访问性
3. 使用 slm health 命令验证 LLM 连接状态

资料来源：Issue #9

Mode C：云端模式

工作原理

Mode C 将嵌入计算和 LLM 推理委托给云端服务，适用于没有本地 GPU 或需要更强算力的场景：

• 远程嵌入：调用 OpenAI、Cohere 等嵌入 API
• 云端推理：使用云端 LLM 进行复杂推理
• 数据主权：重要数据仍存储在本地，仅在必要时调用云端

资料来源：src/superlocalmemory/core/modes.py:80-120

配置示例

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 命令

# 切换运行模式
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

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

性能对比

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

资料来源：src/superlocalmemory/server/unified_daemon.py:50-100

常见问题与解决方案

问题1：模式切换后无响应

症状：执行 slm mode b 后命令卡住或超时

原因：Mode B 需要 Ollama 服务运行，但服务未启动

解决方案：

# 启动 Ollama 服务
ollama serve &

# 验证 Ollama 状态
ollama list

# 再次切换模式
slm mode b

问题2：Mode B 下 LLM 功能不可用

症状：slm recall 返回结果但未进行 LLM 重排序

排查步骤：

# 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

问题3：Docker/Linux 环境下模式识别问题

症状：在 Docker 容器或 Linux 环境中模式功能异常

解决方案：

# 设置环境变量
export SLM_NON_INTERACTIVE=true
export SLM_HOME=/path/to/custom/directory

# 重新初始化
slm setup --force

资料来源：Issue #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 B 和 Mode C 支持配置自定义嵌入端点，这对于非英语用户尤为重要：

mode: b
embedding:
  provider: openai_compatible
  base_url: http://localhost:8080/v1
  model: your-multilingual-model
  api_key: xxxxx

此功能解决了 Issue #16 中用户对非英语语言支持的请求

资料来源：Issue #16

相关文档

• 快速入门指南
• 安装与配置
• 常见问题解答
• 架构设计
• MCP 集成

更新日志

资料来源：src/superlocalmemory/core/modes.py

CLI 参考手册

SuperLocalMemory V3 提供了一个功能完整的命令行界面（CLI），允许用户通过 slm 命令与记忆系统进行交互。本页面详细说明了所有 CLI 命令的用法、参数选项以及常见使用场景。

概述

MCP 工具集是 SuperLocalMemory V3 的核心组件之一，通过标准化的 MCP 协议与各种 AI 工具和 IDE 进行集成。根据 package.json 中的配置，MCP 服务器名称为 io.github.qualixar/superlocalmemory，支持 11 种以上的 IDE 集成，包括 Claude Desktop、Cursor、Windsurf、Continue.dev 等主流 AI 编程工具。

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

MCP 服务器架构

服务端组件

MCP 服务器采用模块化设计，核心组件分布在多个源码文件中：

资料来源：src/superlocalmemory/mcp/server.py

工具注册机制

工具通过 @mcp.tool() 装饰器注册到 MCP 服务器。每个工具都是一个异步函数，返回结构化的 JSON 响应：

@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

核心工具详解

1. slm_remember — 记忆存储

slm_remember 工具用于将信息存储到本地记忆系统。

参数说明：

返回结果：

{
  "id": "mem_abc123",
  "content": "用户提供的记忆内容",
  "importance": 5,
  "tags": ["标签1", "标签2"],
  "project": "my-project",
  "created_at": 1703123456
}

资料来源：src/superlocalmemory/mcp/tools_core.py

2. slm_recall — 记忆检索

slm_recall 工具支持基于语义相似度的记忆检索，使用 Fisher-Rao 度量进行信息几何相似度计算。

参数说明：

返回结果：

{
  "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

3. slm_list_recent — 最近记忆

列出最近添加的记忆条目，按时间倒序排列。

参数说明：

4. slm_status — 系统状态

获取 SuperLocalMemory 系统的运行状态和统计信息。

返回结果：

{
  "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 — 知识图谱构建

基于已有记忆构建知识图谱结构，展示记忆之间的关联关系。

参数说明：

6. slm_switch_profile — Profile 切换

在不同的用户 profile 之间切换，改变记忆检索的作用域。

参数说明：

资料来源：src/superlocalmemory/mcp/tools.py

Mesh 工具集

Mesh 工具集用于分布式场景，支持多机器间的记忆同步。当与 slm-mesh 配合使用时，可以实现跨设备的统一记忆访问。

工具列表

资料来源：src/superlocalmemory/mcp/tools_mesh.py

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：

{
  "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

Cursor IDE

编辑 Cursor 设置中的 MCP 配置，添加以下配置项：

{
  "mcpServers": {
    "superlocalmemory": {
      "command": "superlocalmemory",
      "args": ["mcp", "run"],
      "env": {
        "SLM_PROFILE": "default"
      }
    }
  }
}

资料来源：ide/configs/cursor-mcp.json

其他支持的 IDE

根据项目文档，MCP 工具集还支持以下 IDE 和工具：

资料来源：docs/mcp-tools.md

环境变量配置

MCP 工具集通过以下环境变量进行配置：

注意事项：

• 社区反馈 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

工作流程示例

基本使用流程

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

安全考虑

Profile 隔离

根据 v2.6.0 安全加固版本的设计，所有 MCP 查询端点都实现了 profile 隔离。一个 profile 的记忆永远不会泄露到另一个 profile，即使使用相同的 MCP 连接。

# 每个查询都会自动注入当前 profile 上下文
query_context = {
    "profile": current_profile,
    "isolation_enforced": True,
    "audit_trail": True
}

Trust 框架

V3 引入了 Trust 框架，对 MCP 工具调用进行权限校验：

常见问题与故障排除

问题 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）无法正常工作。

临时解决方案：

在环境变量中直接设置：

export OPENAI_API_KEY="your-key-here"

问题 3：Docker 容器中认知整合问题

Issue #26 报告在 Ubuntu/Debian Docker 容器环境中出现认知整合和追踪问题。建议在容器中设置适当的工作目录和挂载点：

docker run -v ~/.superlocalmemory:/root/.superlocalmemory \
           -e SLM_DATA_DIR=/root/.superlocalmemory \
           your-slm-image

性能优化建议

缓存策略

MCP 工具集利用 ContextCache 进行热点数据缓存：

并发限制

资料来源：src/superlocalmemory/server/ui.py

相关文档

• Universal Architecture（通用架构） — 了解 SuperLocalMemory 的 7 层架构设计
• Installation（安装指南） — 详细的安装和配置教程
• Home（首页） — 项目概览和主要特性
• FAQ（常见问题） — 更多常见问题解答

更新日志

1. 架构概述

1.1 四通道检索模型

SuperLocalMemory V3 采用创新的四通道并行检索架构，每个通道从不同维度评估记忆与查询的相关性：

graph TD
    A[用户查询] --> B[检索引擎]
    B --> C1[语义通道<br/>Semantic Channel]
    B --> C2[Hopfield通道<br/>Hopfield Channel]
    B --> C3[扩散激活通道<br/>Spreading Activation]
    B --> C4[Fisher-Rao通道<br/>Fisher-Rao Metric]
    C1 --> D[通道得分]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E[得分融合]
    E --> F[Top-K 记忆条目]

1.2 核心组件列表

2. 检索引擎

2.1 引擎架构

检索引擎是整个管道的中枢，负责接收用户查询、协调四个通道并行执行、对通道得分进行加权融合，并返回最终排序结果。

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 检索执行流程

# 资料来源：src/superlocalmemory/retrieval/engine.py
async def retrieve(self, query: str, top_k: int = 10, **kwargs) -> List[MemoryEntry]:
    """
    执行四通道并行检索
    
    参数:
        query: 用户查询文本
        top_k: 返回的顶级结果数量
        **kwargs: 传递给各通道的额外参数
    
    返回:
        按融合得分排序的记忆条目列表
    """

2.3 得分融合机制

引擎采用加权几何平均方式融合四通道得分：

# 资料来源：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 嵌入向量检索

语义通道基于向量嵌入的余弦相似度进行记忆召回。每个记忆条目在存储时会被转换为高维向量表示，查询同样被编码为向量，然后通过向量相似度搜索找到最相关的记忆。

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 嵌入配置参数

3.3 实现源码

# 资料来源：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 通道模拟人类大脑的联想记忆机制。当用户查询某个概念时，该通道能够检索与该概念具有关联关系但字面上不包含查询词的记忆条目。

graph LR
    A[查询模式] --> B[Hopfield 网络]
    B --> C[能量函数最小化]
    C --> D[收敛到吸引子]
    D --> E[关联记忆输出]
    
    F[记忆模式<br/>M1, M2, M3...] --> B

4.2 Hopfield 网络参数

4.3 实现原理

# 资料来源：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 图传播算法

扩散激活通道基于记忆之间的语义关系图进行传播检索。当查询激活某个节点时，激活信号会沿着图中的边传播到相邻节点，从而发现间接相关的记忆。

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 扩散参数配置

5.3 实现细节

# 资料来源：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 度量考虑了概率分布的黎曼几何结构。

graph LR
    A[分布 P] -->|参数θ| B[流形 M]
    C[分布 Q] -->|参数φ| B
    B -->|测地线| D[最短路径]
    D -->|长度| E[Fisher-Rao 距离]

6.2 Fisher 信息度量

# 资料来源：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 度量参数

7. 配置与调优

7.1 检索配置选项

7.2 模式选择

# 资料来源：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 环境变量配置

8. 使用模式

8.1 CLI 检索

# 基本检索
slm recall "查找关于 Python 项目的记忆"

# 带过滤条件
slm recall "查找 2024 年的项目" --profile work --tag project

# 限制返回数量
slm recall "查找相关文档" --top 5

8.2 API 检索

# 资料来源：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 工具检索

{
  "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

9.2 Linux/Docker 环境问题

问题: 在 Docker 容器中检索失败。

常见原因:

• 内存不足导致嵌入模型加载失败
• 容器网络隔离阻止 Ollama 访问
• 路径权限问题

解决方案:

1. 增加 Docker 内存限制（建议 4GB+）
2. 使用 --network=host 或配置 Ollama 容器网络
3. 验证数据目录权限

*资料来源*: Issue #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

10. 性能优化建议

10.1 嵌入缓存

启用嵌入结果缓存以加速重复查询：

# 资料来源：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 异步并行执行

# 四通道并行执行
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 — 项目首页
• Universal Architecture — 系统架构
• MCP Integration — MCP 协议集成
• Installation — 安装指南
• FAQ — 常见问题

概述

记忆生命周期是 SuperLocalMemory V2.8.0 引入的核心功能模块，负责管理记忆从创建到最终删除的完整演进过程。系统通过多层次的分析引擎，自动识别重要记忆、次要记忆和过时记忆，并执行相应的存储层迁移、合并和清理操作。

该系统解决了传统记忆系统的核心问题：当记忆数量增长到数千条时，系统性能下降，相关记忆的检索精度降低。生命周期管理通过智能化的组织策略，确保系统长期运行的稳定性和检索效率。

核心架构

生命周期组件关系

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

记忆状态流转

stateDiagram-v2
    [*] --> 新建: slm remember
    新建 --> 活跃: 首次访问
    活跃 --> 热点: 高频访问
    活跃 --> 温热: 中频访问
    活跃 --> 休眠: 低频访问
    休眠 --> 活跃: 再次访问
    休眠 --> 归档: 超时未访问
    热点 --> 温热: 访问下降
    温热 --> 冷层: 持续低频
    冷层 --> 删除: 超过保留期
    归档 --> 活跃: 需要召回
    热点 --> 合并: 碎片整理
    [*] --> 删除: 手动删除

核心组件

合并引擎 (Consolidation Engine)

合并引擎是生命周期管理的核心组件，负责识别可合并的关联记忆并生成高密度记忆表示。

# 资料来源：src/superlocalmemory/core/consolidation_engine.py:1-50
class ConsolidationEngine:
    """信息几何合并引擎，支持4通道检索"""

主要职责：

配置参数：

认知整合器 (Cognitive Consolidator)

认知整合器实现高级记忆整合策略，模拟人类记忆的遗忘曲线和整合机制。

# 资料来源：src/superlocalmemory/encoding/cognitive_consolidator.py:1-30
class CognitiveConsolidator:
    """认知整合器 - 模拟海马体整合机制"""

整合阶段：

1. 提取阶段 — 识别当前会话中的关键事实
2. 整合阶段 — 将新事实与已有记忆关联
3. 固化阶段 — 生成更紧凑的记忆表示
4. 索引更新 — 更新多通道检索索引

修剪引擎 (Pruning Engine)

修剪引擎负责识别和删除不再需要的记忆，释放存储空间。

# 资料来源：src/superlocalmemory/core/pruning_engine.py:1-40
class PruningEngine:
    """智能修剪引擎 - 基于使用模式清理记忆"""

修剪策略：

层管理器 (Tier Manager)

层管理器控制记忆在不同存储层之间的迁移。

# 资料来源：src/superlocalmemory/core/tier_manager.py:1-60
class TierManager:
    """三层存储架构管理器"""

存储层定义：

自适应学习

自适应学习器 (Adaptive Learner)

自适应学习器从用户使用模式中学习，优化记忆组织和检索优先级。

# 资料来源：src/superlocalmemory/learning/adaptive.py:1-80
class AdaptiveLearner:
    """三层自适应学习：技术偏好、项目上下文、工作流模式"""

学习层次：

1. 技术偏好学习 — 识别用户偏好的编程语言、框架和工具
2. 项目上下文学习 — 理解当前项目的技术栈和架构
3. 工作流模式学习 — 掌握用户的常规操作序列和习惯

行为学习器 (Behavioral Learner)

行为学习器从操作结果中学习，实现零 LLM 推理的本地模式识别。

# 资料来源：src/superlocalmemory/learning/behavioral.py:1-100
class BehavioralLearner:
    """行为学习器 - 从操作结果中学习"""

学习机制：

• 追踪记忆召回后的用户反馈（采纳、修改、忽略）
• 分析成功检索与失败检索的模式差异
• 跨项目迁移有效的学习策略
• 无需 LLM 推理，完全基于本地模式识别

存储模型

记忆数据模型

# 资料来源：src/superlocalmemory/storage/models.py:50-120
class MemoryModel:
    """记忆存储模型"""
    fields = [
        "id",           # 唯一标识符
        "content",      # 记忆内容
        "embedding",    # 向量表示
        "topic",        # 主题分类
        "tier",         # 存储层级
        "access_count", # 访问计数
        "last_access",  # 最后访问时间
        "created_at",   # 创建时间
        "importance",   # 重要性评分
        "tags",         # 标签系统
    ]

生命周期元数据

使用方法

CLI 命令

# 查看记忆生命周期状态
slm status --lifecycle

# 手动触发合并操作
slm lifecycle consolidate

# 查看存储层分布
slm tier list

# 强制修剪低价值记忆
slm lifecycle prune --dry-run

# 导出生命周期报告
slm lifecycle report --format json

API 端点

# 获取记忆层级信息
GET /api/v3/lifecycle/tiers

# 触发合并检查
POST /api/v3/lifecycle/consolidate

# 获取修剪建议
GET /api/v3/lifecycle/pruning-candidates?threshold=0.3

# 更新记忆保留策略
PUT /api/v3/lifecycle/policy

配置选项

全局配置

# ~/.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

环境变量

常见问题

Linux/Docker 环境下的认知整合问题

用户在 Linux 或 Docker 容器环境中报告了认知整合和追踪相关的问题。这些问题通常与容器资源限制或 cgroup 隔离相关。

解决方案：

1. 确保容器分配足够的内存资源
2. 检查 /sys/fs/cgroup 是否正确挂载
3. 对于大规模记忆库，考虑使用主机网络模式

# 推荐 Docker 配置
docker run --memory=4g --memory-swap=4g \
  --cgroupns=host \
  -v ~/.superlocalmemory:/root/.superlocalmemory \
  your-slm-image

合并操作耗时过长

当记忆数量达到数千条时，合并操作可能需要较长时间。系统提供了增量合并策略。

# 使用增量模式（每次只处理有限数量）
slm lifecycle consolidate --incremental --batch-size=50

记忆层级自动迁移不生效

如果记忆未按预期迁移到正确的层级，请检查：

1. SLM_DATA_DIR 环境变量是否正确设置（当前版本支持）
2. 访问统计是否正常记录
3. 时间同步是否正确

与其他系统的集成

行为学习与检索系统

行为学习器的输出直接影响 4 通道检索的权重分配：

graph LR
    A[行为学习] --> B[重要性权重]
    A --> C[上下文权重]
    B --> D[4通道检索]
    C --> D
    D --> E[检索结果排序]

企业合规集成

记忆生命周期与合规模块协同工作：

• 访问审计 — 所有层级迁移都有完整日志
• 保留策略 — 符合 EU AI Act 等法规要求
• 数据导出 — 支持完整生命周期数据的导出

See Also

• Home — 主页和功能概览
• Universal-Architecture — 7层系统架构
• Installation — 安装和配置指南
• MCP-Integration — MCP 协议集成
• Universal-Skills — 通用技能命令

功能概述

SuperLocalMemory 的多机 Mesh 网络基于点对点（Peer-to-Peer）架构设计，旨在实现跨机器的记忆同步和共享。每个节点既可以是记忆的消费者，也可以是记忆的生产者，所有数据交互通过加密通道进行，确保数据隐私和安全。

当前实现中，SLM 守护进程默认绑定 127.0.0.1，这限制了系统在多机环境中的使用。社区用户报告指出，在运行 7 台机器的 WireGuard mesh 网络环境中，这一限制成为主要瓶颈。资料来源：GitHub Issue #23

架构设计

网络拓扑

SuperLocalMemory Mesh 网络采用混合拓扑结构，结合星型拓扑的易管理性和网状拓扑的高可靠性特点。每个节点维护与其他节点的连接状态，并能够动态发现和加入网络。

graph TD
    A[节点 A<br/>192.168.1.10] <--> B[节点 B<br/>192.168.1.11]
    A <--> C[节点 C<br/>192.168.1.12]
    B <--> D[节点 D<br/>192.168.1.13]
    C <--> D
    B <--> C
    
    subgraph WireGuard Mesh
        A
        B
        C
        D
    end
    
    E[记忆数据库<br/>SQLite] --> A
    F[记忆数据库<br/>SQLite] --> B
    G[记忆数据库<br/>SQLite] --> C
    H[记忆数据库<br/>SQLite] --> D

核心组件

资料来源：wiki-content/v2-archive/README.md

配置指南

环境变量配置

SuperLocalMemory 支持通过环境变量配置数据目录和绑定地址。在多机部署场景下，配置 SL_MEMORY_PATH 可指定非默认数据存储位置：

# 设置自定义数据目录
export SL_MEMORY_PATH="/mnt/shared/slm-data"

# 设置监听地址（需要支持可配置绑定）
export SLM_HOST="0.0.0.0"

资料来源：src/superlocalmemory/cli/setup_wizard.py:34

守护进程配置

守护进程通过 unified_daemon.py 统一管理服务生命周期。在多机环境中，守护进程需要配置为监听所有可用网络接口：

# 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/598b2fc1ce9af40b8b58ac24d2db4827513300b0/CHANGELOG.md",
            _slm_version,
        )

资料来源：src/superlocalmemory/server/unified_daemon.py

WebSocket 实时通信

SuperLocalMemory V3 实现了基于 WebSocket 的实时通信机制，支持多客户端同时连接和数据推送。服务端通过 ws_manager 管理所有活跃连接：

# 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

CORS 配置

多机环境中，WebSocket 连接需要正确配置跨域资源共享：

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

API 服务端点

FastAPI 服务提供了完整的 REST API 接口，支持多机环境下的记忆查询和管理操作：

class SearchRequest(BaseModel):
    query: str

资料来源：src/superlocalmemory/server/api.py

主要路由模块

资料来源：src/superlocalmemory/server/ui.py:71-79

使用场景

家庭实验室多机部署

在家庭实验室环境中，用户可以部署多台运行 SuperLocalMemory 的机器，通过 WireGuard VPN 连接形成私有 mesh 网络。每台机器运行独立的记忆实例，同时可以共享部分记忆给其他节点。

典型配置包括 7 台机器的部署，通过 WireGuard mesh 实现全网格连接。资料来源：GitHub Issue #23

AI 代理团队协作

多个专业化的 AI 代理可以分别运行在不同的机器上，通过 Mesh 网络共享知识库。每个代理维护私有记忆，同时可以访问团队共享的全局记忆。

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

第三方集成

LlamaIndex 集成

SuperLocalMemory 支持作为 LlamaIndex 的聊天存储后端使用。在多机环境中，可以配置自定义数据库路径实现跨节点共享：

# 使用自定义数据库文件实现多机共享
chat_store = SuperLocalMemoryChatStore(
    db_path="/path/to/shared/memory.db"
)

• 内容: JSON 序列化的消息数据
• 标签: llamaindex:chat:<session_key> 用于会话隔离
• 项目: llamaindex 用于标识
• 重要性: 3（较低，聊天消息不会干扰搜索结果）

资料来源：ide/integrations/llamaindex/README.md

LangChain 集成

LangChain 用户同样可以使用 SuperLocalMemory 作为消息历史存储后端：

from langchain_superlocalmemory import SuperLocalMemoryChatMessageHistory

# 跨节点共享对话历史
history = SuperLocalMemoryChatMessageHistory(
    session_id="my-session",
    db_path="/path/to/shared/memory.db",
)

资料来源：ide/integrations/langchain/README.md

常见问题

绑定地址限制

问题: SLM 守护进程和 slm-mesh broker 硬编码绑定 127.0.0.1，无法接受外部连接。

解决方案: 社区正在开发 SLM_HOST 功能以支持可配置的绑定地址。在生产环境中，可以考虑使用反向代理（如 nginx）将外部请求转发到本地服务。

资料来源：GitHub Issue #23

Docker 容器中的网络问题

问题: 在 Docker 容器中运行 SuperLocalMemory 时可能出现认知整合和追踪问题。

环境信息:

• Ubuntu/Debian Docker 容器
• Python 3.12
• Ollama 提供服务

排查建议:

1. 检查容器网络模式配置
2. 确保端口映射正确
3. 验证 Ollama 服务可达性

资料来源：GitHub Issue #26

数据目录配置未生效

问题: SLM_DATA_DIR 环境变量在某些版本中未被正确使用。

临时解决方案: 使用 SL_MEMORY_PATH 环境变量替代：

export SL_MEMORY_PATH="/自定义/路径"

资料来源：GitHub Issue #10

版本历史

资料来源：CHANGELOG.md

命令行接口

多机部署场景下常用的 CLI 命令：

# 启动守护进程（自动检测并启动）
slm status

# 检查系统状态
slm status

# 切换配置文件
slm switch-profile <profile-name>

# 列出最近记忆
slm list-recent

# 查看网络连接状态
slm recall "network status"

资料来源：src/superlocalmemory/cli/main.py

自动启动机制

V3.4.4 引入了守护进程自动启动机制，确保多机环境中的服务可用性：

_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

后续发展

多机 Mesh 网络功能正在积极开发中，未来版本计划支持：

• 多作用域记忆: 个人、全局、共享作用域及作用域感知检索
• 可配置嵌入端点: 支持 OpenAI 兼容 API 的本地嵌入服务
• 增强的跨节点同步: 更高效的增量同步机制

资料来源：GitHub Issue #20、GitHub Issue #16

相关链接

• 官方文档
• 安装指南
• 架构说明
• MCP 集成
• 常见问题
• GitHub 问题反馈
• 更新日志

概述

SuperLocalMemory V3 采用 YAML 配置文件配合环境变量的双重配置机制。系统支持两种运行模式：

• Mode A：零 LLM 推理模式，使用 Fisher-Rao 度量进行纯数学相似度计算
• Mode B：使用 LLM 进行语义理解和推理

配置文件位于 ~/.superlocalmemory/config.yaml，首次运行时会通过设置向导自动生成。

资料来源：src/superlocalmemory/core/config.py:1-100

配置架构

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

设置自定义数据目录，所有数据库文件和配置文件将存储在此目录下。

# 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

在脚本或容器环境中禁用交互式提示，自动使用默认值。

SLM_NON_INTERACTIVE=1 slm setup

配置文件结构

完整的 config.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，使用纯数学方法进行记忆检索：

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。

资料来源：src/superlocalmemory/core/config.py:80-100

Mode B（LLM 模式）

Mode B 使用 LLM 进行语义理解和推理：

mode: "b"

mode_b:
  provider: "ollama"  # 支持: ollama, openai, anthropic, localai
  model: "llama3.2"
  api_base: "http://localhost:11434"
  api_key: ""  # 非 Ollama 提供商需要

支持的提供商：

⚠️ 已知问题：api_key 在 Mode B 配置中可能被静默丢弃，导致 LLMBackbone.is_available() 返回 False。参见 Issue #9。

资料来源：src/superlocalmemory/core/config.py:100-130

向量模型配置

Mode B 支持自定义嵌入端点：

mode_b:
  provider: "openai"
  embedding_provider: "openai"
  embedding_model: "text-embedding-3-small"
  embedding_api_base: "https://api.openai.com/v1"

💡 功能请求：社区请求支持 OpenAI 兼容的本地嵌入端点以提升非英语语言的潜在支持。参见 Issue #16。

API 服务器配置

API 服务器负责提供 REST API 和 WebSocket 接口：

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。

速率限制

api:
  rate_limit:
    read: 120   # 读操作速率限制
    write: 30   # 写操作速率限制

实现代码位于 superlocalmemory.infra.rate_limiter.RateLimiter：

_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，路径由环境变量或默认路径决定：

MEMORY_DIR = Path.home() / ".superlocalmemory"
DB_PATH = MEMORY_DIR / "memory.db"

数据目录结构

~/.superlocalmemory/
├── config.yaml          # 配置文件
├── memory.db            # SQLite 数据库
├── .setup-complete      # 设置完成标记
├── learning/            # 学习数据目录
└── backups/             # 自动备份目录

V2 数据迁移

如果检测到 V2 安装，会自动提示迁移：

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

初始化向导

首次运行时，系统自动调用设置向导：

slm setup

向导流程

graph TD
    A[检测交互模式] --> B{是否为交互式?}
    B -->|是| C[显示欢迎信息]
    B -->|否| D[使用默认配置]
    C --> E[下载模型]
    E --> F[验证安装]
    F --> G[创建配置文件]
    G --> H[设置完成标记]
    D --> H

非交互模式

SLM_NON_INTERACTIVE=1 slm setup

资料来源：src/superlocalmemory/cli/setup_wizard.py:50-100

常见配置问题

问题：配置未生效

原因：配置文件格式错误或权限问题

解决方案：

1. 检查 ~/.superlocalmemory/config.yaml 是否存在
2. 验证 YAML 语法
3. 确保文件可读

cat ~/.superlocalmemory/config.yaml

问题：Mode B LLM 不可用

原因：api_key 未正确传递

解决方案：

1. 检查 config.yaml 中 mode_b.api_key 是否设置
2. 验证 LLM 服务是否运行
3. 确认 api_base 配置正确

slm status

问题：数据库锁定

原因：多个进程同时访问数据库

解决方案：

1. 确保只有一个 slmd 守护进程运行
2. 检查是否有僵尸进程

pkill -f slmd
slm daemon

问题：Docker 容器中响应慢

原因：容器资源限制或模型加载延迟

参见 Issue #26 获取详细排查指南。

配置验证

使用 slm status 命令验证配置：

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

相关文档

• 快速入门指南
• 架构设计
• API 参考
• MCP 集成

Pitfall Log / 踩坑日志

项目：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