项目定位与设计目标

SuperLocalMemory（SLM）是一个面向 LLM 智能体的本地优先（local-first）记忆与优化中间件系统，旨在为 Claude Code、Cursor、Codex、Gemini 等多种 AI 编程助手提供持久化记忆、上下文压缩与缓存加速能力。系统强调"数据主权"——所有记忆、向量索引与配置默认存放在用户本地数据目录中。wiki-content/v2-archive/README.md 中描述，v2.1.0 之后系统已从原先的 4 层架构扩展为 7 层通用架构，新增了 Universal Access 层、MCP Integration 层与 Skills 层。资料来源：wiki-content/v2-archive/README.md:1-50。

项目在 v2.6.0 至 v2.8.0 之间引入了 Memory Lifecycle、Behavioral Learning 与 Enterprise Compliance 等企业级能力，并在 v3.6.3 修复了影响 Claude Code、Codex CLI 流量缓存的关键 bug——这是社区反馈最密集的功能领域之一。资料来源：community_context #v3.6.3。

核心系统分层

当前代码库反映出以下层次化结构（自下而上）：

1. 存储层（Storage）：基于 SQLite 的事件与记忆持久化，事件表结构定义在 src/superlocalmemory/cli/ingest_cmd.py 的导入逻辑中（字段包括 session_id, project_path, tool_name, event_type, input_summary, output_summary, created_at）。资料来源：src/superlocalmemory/cli/ingest_cmd.py:1-50。
2. 检索层（Retrieval）：提供 slm-recall、slm-remember 等核心语义检索能力（详见 SKILL 文档）。
3. 压缩层（Compression）：由 src/superlocalmemory/optimize/compress/router.py 统一调度，按消息类型分派至 prose、code、CCR 三条子路径。该 router 对 tool_result 块特别处理——保留其块结构但压缩文本内容，正是 Claude Code 流量中体积最大的部分。资料来源：src/superlocalmemory/optimize/compress/router.py:1-80。
4. 代码压缩子模块：extractive_code.py 实现 AST 感知（tree-sitter）与正则回退两条路径，支持 Python、JavaScript、Go、Rust、Java、C++。资料来源：src/superlocalmemory/optimize/compress/extractive_code.py:1-40。
5. 散文压缩子模块：prose_llmlingua.py 引入 Microsoft LLMLingua-2 模型（XLM-RoBERTa 微调版），仅在 compress_mode == "aggressive" 时启用，导入失败时安全回退到原文。资料来源：src/superlocalmemory/optimize/compress/prose_llmlingua.py:1-30。
6. 缓存层（Cache）：通过 openai_adapter.py 与 anthropic_adapter.py 包装原生 SDK，构造确定性 cache key（基于 model + messages + 其他参数），并支持异步客户端检测。资料来源：src/superlocalmemory/optimize/adapters/openai_adapter.py:1-60, src/superlocalmemory/optimize/adapters/anthropic_adapter.py:1-60。
7. 代理注册层（Agent Registry）：_agent_registry.py 维护 Claude Code、Antigravity（agy）、Cline、OpenCode、Cursor 等多种 IDE 的重定向元数据，每条记录包含 binary、mechanism、protocol、print_only、help_text 等字段，便于 setup 时自动重写配置文件。资料来源：src/superlocalmemory/optimize/adapters/_agent_registry.py:1-60。

初始化与配置工作流

setup_wizard.py 实现了 10 步交互式安装流程，从 Mode 选择到最终验证。CLI 端通过 main.py 暴露 slm cache 与 slm compress 等子命令族，支持 status/mode/code/prose/ccr 等子操作，便于运行期调参。资料来源：src/superlocalmemory/cli/main.py:1-60。

flowchart TD
    A[Step 1: Mode A/B] --> B[Step 2: Daemon 模式]
    B --> C[Step 3: Mesh 启用?]
    C --> D[Step 4: Adapters 启用]
    D --> E[Step 8: Entity Compilation]
    E --> F[Step 9: Skill Evolution]
    F --> G[Step 10: 验证 + v3.4.26 options]
    G --> H[输出安装摘要]

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

优化层与外部代理集成

压缩路由器（router.py）维护一个保护索引机制——protect_indices 与 is_tool_msg 联合决定哪些消息块保留原样，避免破坏 tool_use / tool_result 的语义结构。代码路径 A（tree-sitter）优先于路径 B（正则），两者均通过单元测试。

代理层通过 SDK 适配器与 OpenAI / Anthropic 客户端对接，在保留原始 client 的同时挂载 chat 或 messages 代理对象，实现零侵入式缓存注入。_agent_registry.py 中的 help_text 字段为 print-only 客户端（如 Cursor、OpenCode）提供手动配置指引，承认并非所有 IDE 都能通过环境变量自动重写。社区 issue #29 指出，本地 llama.cpp 在 OpenAI provider 模式下因严格的 API Key 约束被 Web UI 拦截，说明 SDK 适配层与 UI 表单层之间的耦合仍是需要关注的设计点。资料来源：community_context #29。

CLI 中的 slm cache semantic on/off 与 slm compress mode safe/aggressive 两条命令构成运行期调优主轴；--tenant 与 --json 标志则保证多租户与 agent-native 输出能力。资料来源：src/superlocalmemory/cli/main.py:1-60。

See Also

• MCP-Integration — MCP 协议在 11+ IDE 上的接入指南
• Installation — 完整安装步骤与排错
• FAQ — 常见问题（含多作用域记忆、SLM_HOST 等 RFC）

概述

SuperLocalMemory（SLM）是一套面向 LLM 代理的本地优先（local-first）记忆系统，由 Varun Pratap Bhardwaj 创建并以 Elastic License 2.0 / AGPL-3.0-or-later 双协议分发。本页聚焦其"安装、配置与运行模式"层面的工程实现：覆盖从首次 slm setup 向导、数据目录布局、到 config.json / optimize.json 双层配置体系，以及 Mode A / Mode B、守护进程（daemon）、Mesh、实体编译（Entity Compilation）、技能演化（Skill Evolution）等运行时开关。

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

安装流程

系统前置条件

SLM 安装脚本在向导开始处会校验 Python 版本与运行环境。社区问题 #32 反馈在 Ubuntu 22.04 LTS（系统自带 Python 3.10.12）下 slm setup 直接失败，向导要求 3.11+ 才能继续。资料来源：issue #32

`slm setup` 十步向导

src/superlocalmemory/cli/setup_wizard.py 实现了交互式配置流程，按顺序提示用户选择：

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

向导完成后会写入数据目录（默认 ~/.slm/），并对 config.json 做"模式变更"保存（config.save(mode_change=True)），确保重启后行为一致。技能演化配置由于 SLMConfig.save() 不序列化 evolution 字段，setup 步骤中采用手工 json.loads → 修改 → json.dumps 的方式直接覆写 config.json，这是已知实现细节。资料来源：src/superlocalmemory/cli/setup_wizard.py:40-60

v3.4.26 数据目录安全检查

prompt_v3426_options() 与 validate_install_data_dir() 协同工作，对安装数据目录进行安全审计；若不通过会向用户打印原因但不会中断向导。资料来源：src/superlocalmemory/cli/setup_wizard.py:100-120

运行模式与配置

Mode A 与 Mode B

Wiki v2.1.0 文档将架构从 4 层扩展为 7 层（新增 Universal Access、MCP Integration、Skills 三层），但其底层仍以两种模式运行：

• Mode A：完全本地，向量库与 LLM 推理皆在本地。
• Mode B：本地向量库 + 远程 LLM API（OpenAI、Anthropic 等）。

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

优化层配置：`OptimizeConfig`

src/superlocalmemory/optimize/config/schema.py 中的 OptimizeConfig 是优化层（缓存、压缩、定价、TTL、Provider）的中心配置对象。其 as_dict() 方法输出包含：缓存键、压缩模式（safe / aggressive）、ttl.exact_seconds / ttl.semantic_seconds / ttl.ccr_seconds、Provider 列表、Pricing 字典、Phoenix 监控端口等。资料来源：src/superlocalmemory/optimize/config/schema.py:1-40

压缩子系统细粒度开关示例：

compress_enabled:     bool
compress_mode:       "safe" | "aggressive"
compress_code:       bool    # AST 结构感知
compress_prose:      bool    # 仅 prose，禁 JSON/code
compress_ccr:        bool    # Compressed Context Record
compress_llmlingua_allow_download: bool

适配器注册表

src/superlocalmemory/optimize/adapters/_agent_registry.py 定义了 11+ IDE 客户端的注册信息，区分 print-only（如 Cursor、OpenCode、Antigravity）与 config-file（如 Cline 写入 VS Code settings.json 的 cline.openAiApiBase）。其协议列还区分 openai 与 anthropic 两类 API 形态，决定拦截层如何归一化请求。资料来源：src/superlocalmemory/optimize/adapters/_agent_registry.py:1-40

常见配置问题与社区反馈

`base_dir` 未持久化（Issue #28）

用户报告 config.json 中的 base_dir 在 SLMConfig.load() 时被忽略，且 save() 不写回。临时方案是手动维护 base_dir 或在运行前注入环境变量。资料来源：issue #28

本地 `llama.cpp` 端点被强制要求 API Key（Issue #29）

Web UI 在 OpenAI Provider 模式下对未鉴权的本地 llama.cpp 服务器仍校验 API Key 字段，导致连接被拒。资料来源：issue #29

缺少环境变量与配置键的统一文档（Issue #37）

社区明确请求一份"所有受支持环境变量与配置键"的中央目录，目前分散在 optimize/config/schema.py、wizard_v3426_options.py 与各 CLI 子命令中。资料来源：issue #37

守护进程与 Mesh 绑定地址

Issue #23 反馈 daemon 与 slm-mesh broker 默认硬编码 127.0.0.1，无法直接服务跨机 WireGuard mesh，需要 SLM_HOST 类环境变量覆盖。资料来源：issue #23

故障排查清单

1. Python 版本不符 → 升级至 3.11+，或使用 uv / pyenv 隔离环境。
2. config.json 字段丢失 → 检查 SLMConfig.save(mode_change=True) 是否被调用；evolution 段需手动确认序列化。
3. 缓存未命中 → v3.6.3 修复了 has_tools 守卫误判带 tools 数组的客户端，确认已升级。
4. Mesh 连接失败 → 临时改用 SLM_HOST=0.0.0.0 并放行端口。

See Also

• Universal-Architecture（7 层架构）
• MCP-Integration（MCP 集成）
• Home（v2.1.0 Wiki 首页）
• FAQ（常见问题）

1. 定位与作用

V3.6 Optimize 是 SuperLocalMemory (SLM) 在 src/superlocalmemory/optimize/ 下的统一优化层，承担三项核心职责：调用前缓存（Cache）、调用前消息压缩（Compress）、以及多轮上下文对齐（Alignment）。它位于 LLM 客户端 SDK 与上游 provider 之间，通过透明代理或适配器（adapter）形式挂载，对用户代码几乎无侵入。

CLI 主入口在 slm optimize / cache / compress 三个子命令下挂载，无需启动守护进程即可读写配置 资料来源：src/superlocalmemory/cli/main.py:1-120。OptimizeConfig 数据类集中管理所有可调字段（语义缓存、压缩、TTL、提供商、计价、Prometheus 端口等），并支持通过 as_dict() 序列化 资料来源：src/superlocalmemory/optimize/config/schema.py:1-200。

2. 缓存子系统（Cache）

缓存采用 P1 精确缓存优先，P2 语义缓存兜底 的两级架构。

• 精确缓存：基于 KeyBuilder 的请求指纹直接命中。
• 语义缓存（VCacheSemantic）：在精确未命中时启用，结合 vCache 的 per-item online-MLE 决策（arXiv:2502.03771）、SAFE-CACHE 质心防御（Nature Scientific Reports 2026）以及双阈值验证改写。默认关闭，需显式开启 资料来源：src/superlocalmemory/optimize/cache/semantic.py:1-60。
• 多轮上下文指纹：ContextKeyBuilder 用 64-bit 指纹作为语义命中的辅助作用域守卫，避免语义相近但会话上下文不同的回合被误复用 资料来源：src/superlocalmemory/optimize/cache/context_key.py:1-60。
• SDK 适配器：SLMAnthropicAdapter 透明包装 anthropic.Anthropic 与 AsyncAnthropic 的 messages 接口，自动注入缓存键 资料来源：src/superlocalmemory/optimize/adapters/anthropic_adapter.py:1-90。

社区关键修复：v3.6.3 之前，代理层 if not has_tools and cache: 的守卫导致 Claude Code / Codex CLI / Claude Desktop 这类必带 tools 数组的客户端 100% 走不到缓存路径。v3.6.3 移除该结构性守卫后，工具型客户端的缓存才真正生效——这是 Optimize 层近期最重要的回归修复。

3. 压缩子系统（Compress）

压缩由 CompressRouter 统一调度，按内容类型分派到不同后端：

flowchart LR
    A[LLM 请求消息] --> B[CompressRouter]
    B -->|code 块| C[CodeCompressor<br/>AST 抽取]
    B -->|prose 文本| D[LLMLingua-2<br/>opt-in]
    B -->|json / schema| E[结构保护跳过]
    B -->|tool_result| F[块内文本压缩]
    C --> G[保护最近 N 条]
    D --> G
    F --> G
    G --> H[对齐 / CCR 引用]

• CodeCompressor：AST 感知的抽取式压缩器，支持 Python / JavaScript / Go / Rust / Java / C++。若安装 tree-sitter-language-pack 则走 AST 路径，否则回退到正则签名抽取；body 用 // [slm: body compressed — retrieve with ccr_id=…] 桩替换 资料来源：src/superlocalmemory/optimize/compress/extractive_code.py:1-90。
• LLMLingua-2 散文压缩：仅对叙事/散文内容启用，强制要求 compress_mode == "aggressive"；模型来自 Microsoft Research + MIT（XLM-RoBERTa 微调的 token 二分类器）。导入失败时 fail-open 返回原文 资料来源：src/superlocalmemory/optimize/compress/prose_llmlingua.py:1-60。
• CCR（Compress-Compute-Retrieve）：被压缩的 body 在 CCR 中保留原始内容，可通过 ccr_id 取回；属有损压缩但可逆 资料来源：src/superlocalmemory/optimize/compress/router.py:1-90。
• 保护机制：compress_protect_recent（默认 4 条）保留最近消息不被压缩；compress_align 控制块级结构对齐。

4. 配置模型与 CLI 入口

CLI 暴露 slm optimize …、slm cache exact|semantic on|off、slm compress status|mode|code|prose|ccr 等子命令；非交互式 setup_wizard 会在安装阶段自动启用实体编译、代码图与技能演化，并把它们持久化到 config.json 资料来源：src/superlocalmemory/cli/setup_wizard.py:1-160、src/superlocalmemory/cli/main.py:1-120]()。运行时帮助页通过 slm help-optimize <topic> 输出，可定位到 cache、semantic、compress、safety 等小节 资料来源：src/superlocalmemory/cli/help_cmd.py:1-60`。

5. 常见失败模式与排障建议

• 工具型客户端命中率仍为 0：确认已升级到 ≥ v3.6.3，否则受 has_tools 守卫影响。
• LLMLingua-2 未触发：检查 compress_mode == "aggressive" 与 compress_prose == True；散文模型首次使用需联网下载（compress_llmlingua_allow_download 显式开启）。
• 跨会话误命中：检查 ContextKeyBuilder 的 window_turns（默认 3）与 semantic_centroid_min_similarity（默认 0.85）。
• 压缩破坏 JSON / 代码语义：确认 compress_json 与 compress_align 处于启用状态；Router 会跳过结构性内容。

See Also

• Universal-Architecture — Optimize 层所处的 7 层整体架构
• MCP-Integration — 适配 MCP 传输时的缓存/压缩边界
• Installation — slm setup 中 Optimize 相关开关位置

概述

SLM 在 v2.1.0 之后形成了「单数据库 + 多入口」架构。CLI 命令、Claude Code Hooks、MCP 服务器以及各家 IDE（Claude Desktop、Cursor、Windsurf、Continue.dev、ChatGPT、Perplexity、Zed、OpenCode、Antigravity、Cody、Aider）都通过统一的本地存储后端访问记忆。Hook 与 MCP 共同负责把「会话上下文」与「长期记忆」对接起来，避免在 IDE 中反复粘贴历史。资料来源：wiki-content/v2-archive/README.md:1-58

在 CLI 入口层，slm 命令会在第一次使用时自动触发安装向导，并按需自动拉起守护进程；setup、mcp、config、migrate 等命令被显式排除在自动启动之外，以便它们能在守护进程未运行时独立完成配置读写。资料来源：src/superlocalmemory/cli/main.py:165-201

MCP 服务器集成

MCP（Model Context Protocol）是 SLM 对外暴露工具、资源与提示词的标准通道。安装过程中自动注册的 MCP 端点会暴露 6 个工具、4 个资源和 2 个提示词，IDE 客户端只需在 MCP 配置中指向本地 slm 即可。资料来源：wiki-content/v2-archive/README.md:25-36

在代理与适配层，OpenAI 与 Anthropic SDK 都拥有独立适配器，用于将 LLM 请求包装为带缓存的客户端实例：

class SLMOpenAIAdapter:
    def __init__(self, client, cache_manager, config, tenant_id="default"):
        self._is_async = _detect_async_openai(client)
        self.chat = _ChatCompletionsProxy(self)

资料来源：src/superlocalmemory/optimize/adapters/openai_adapter.py:14-31。Anthropic 适配器结构类似，会自动检测同步/异步客户端并代理 messages 调用。资料来源：src/superlocalmemory/optimize/adapters/anthropic_adapter.py:24-44

压缩层通过路由器对请求体做内容分块，再由 CCRStore 存储原始文本，对外暴露 headroom_retrieve MCP 工具，供 LLM 在需要时按 ccr_id 拉回原始内容：

def get_mcp_tool_definition(self) -> dict:
    return {
        "name": "headroom_retrieve",
        "description": "Retrieve the original (pre-compression) text ...",
        "inputSchema": {"type": "object", "properties": {"ccr_id": {"type": "string"}}, "required": ["ccr_id"]},
    }

资料来源：src/superlocalmemory/optimize/compress/ccr.py:42-72。路由器还会按消息类型区分：纯文本直接走压缩管线，tool_result 块则仅压缩其文本内容而保留 JSON 结构，从而避免破坏 Claude Code/Codex 这类长工具输出。资料来源：src/superlocalmemory/optimize/compress/router.py:10-58

Claude Code Hooks 与会话管理

Hooks 是 SLM 接入 Claude Code 的「隐形通道」。CLI 通过 cmd_hooks 提供 install、remove、status 三个动作，安装时可附带 --gate 开关决定是否启用实验性的 session_init 强制门控：

def cmd_hooks(args):
    action = getattr(args, "action", "status")
    include_gate = getattr(args, "gate", False)
    if action == "install":
        result = install_hooks(include_gate=include_gate)

资料来源：src/superlocalmemory/cli/commands.py:1-23

安装钩子的同时会触发「技能包」的同步部署（S9-DASH-11）：通过 importlib.resources 定位内置 skill 资源后拷贝到 ~/.claude/skills/，从而让 slm-recall、slm-remember 等斜杠命令在 Claude Code 中立即可用，避免 npm 与 pip 安装路径下 skill 行为不一致。资料来源：src/superlocalmemory/cli/commands.py:23-44

mcp 命令与 hooks 配合：hooks 在会话开始时通知守护进程初始化上下文，结束时写入摘要，从而保持记忆与 IDE 行为同步。

IDE 与分布式配置实践

典型 IDE 配置

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

常见故障与社区反馈

• 会话无 sessionId（#35）：在 Claude 中通过自然语言开/关会话时，hooks 不会显式返回 sessionId，导致结束时无法定位记录。建议显式调用 slm session start 或检查 ~/.claude/settings.json 中钩子是否被注入。资料来源：社区问题 #35。
• HTTP MCP Host 头限制（#36）：嵌入式 HTTP MCP 传输对 Host 头做了严格校验，分布式 LXC 部署需要将 SLM_HOST 指向可被远程 MCP 客户端解析到的地址，避免被默认的 127.0.0.1 拒绝。资料来源：社区问题 #36。
• Ubuntu 22.04 安装失败（#32）：系统自带的 Python 3.10 不满足 slm setup 的最低要求（3.11+），应先安装 deadsnakes PPA 或使用 pyenv 升级。资料来源：社区问题 #32。
• 本地 llama.cpp 鉴权（#29）：Web UI 在 OpenAI Provider 下要求 API Key，导致无认证本地端点被拒，需要在提供方配置中允许空 Key。资料来源：社区问题 #29。

守护进程行为

CLI 在执行绝大多数命令时都会自动拉起守护进程，从而保证 hooks、MCP 请求和直接 CLI 调用看到的记忆状态一致；只有 setup、mcp、config 等配置类命令显式跳过自动启动，避免在守护进程未就绪时反复启动。资料来源：src/superlocalmemory/cli/main.py:178-201

See Also

• Home
• Installation
• Universal-Architecture
• MCP-Tools
• FAQ

Pitfall Log / 踩坑日志

项目：qualixar/superlocalmemory

摘要：发现 39 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval。

1. 安装坑 · 来源证据：RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/20 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：superlocalmemory pi.dev integration

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：superlocalmemory pi.dev integration
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/31 | 来源类型 github_issue 暴露的待验证使用条件。

3. 配置坑 · 来源证据：bug: BackendOrchestrator uses DatabaseManager "conn" attribute which doesn't exist, silently breaking schema v3.4.5 mig…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: BackendOrchestrator uses DatabaseManager "conn" attribute which doesn't exist, silently breaking schema v3.4.5 migration on every boot
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/47 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 失败模式：security_permissions: GitHub issue body — qualixar SLM_HOST feature request

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: GitHub issue body — qualixar SLM_HOST feature request
• 对用户的影响：Developers may expose sensitive permissions or credentials: GitHub issue body — qualixar SLM_HOST feature request
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/23 | GitHub issue body — qualixar SLM_HOST feature request

5. 安全/权限坑 · 来源证据：Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" returns 401 despite healthy bac…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" returns 401 despite healthy backend (v3.6.9)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/38 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：Three Dashboard UI Issues — Root Causes, Verified Fixes, and Suggested Official Solutions (v3.6.11)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Three Dashboard UI Issues — Root Causes, Verified Fixes, and Suggested Official Solutions (v3.6.11)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/40 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

7. 安装坑 · 失败模式：installation: Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" retur...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" returns 401 despite healthy backend (v3.6.9)
• 对用户的影响：Developers may fail before the first successful local run: Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" returns 401 despite healthy backend (v3.6.9)
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/38 | Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" returns 401 despite healthy backend (v3.6.9), failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/38 | Dashboard: Brain page stuck on "Couldn't load Brain" and LLM Settings "Test Connection" returns 401 despite healthy backend (v3.6.9)

8. 安装坑 · 失败模式：installation: Feature Request: Roadmap for OpenClaw support and distributed agent deployments

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Feature Request: Roadmap for OpenClaw support and distributed agent deployments
• 对用户的影响：Developers may fail before the first successful local run: Feature Request: Roadmap for OpenClaw support and distributed agent deployments
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/33 | Feature Request: Roadmap for OpenClaw support and distributed agent deployments

9. 安装坑 · 失败模式：installation: Feature: Have opening and closing sessions available as direct calls on top of the existing M...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Feature: Have opening and closing sessions available as direct calls on top of the existing MCP tool calls
• 对用户的影响：Developers may fail before the first successful local run: Feature: Have opening and closing sessions available as direct calls on top of the existing MCP tool calls
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/49 | Feature: Have opening and closing sessions available as direct calls on top of the existing MCP tool calls

10. 安装坑 · 失败模式：installation: HTTP MCP: Host header restriction and port conflict with stdio in distributed LXC setup

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: HTTP MCP: Host header restriction and port conflict with stdio in distributed LXC setup
• 对用户的影响：Developers may fail before the first successful local run: HTTP MCP: Host header restriction and port conflict with stdio in distributed LXC setup
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/36 | HTTP MCP: Host header restriction and port conflict with stdio in distributed LXC setup, failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/36 | HTTP MCP: Host header restriction and port conflict with stdio in distributed LXC setup

11. 安装坑 · 失败模式：installation: Three Dashboard UI Issues — Root Causes, Verified Fixes, and Suggested Official Solutions (v3...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Three Dashboard UI Issues — Root Causes, Verified Fixes, and Suggested Official Solutions (v3.6.11)
• 对用户的影响：Developers may fail before the first successful local run: Three Dashboard UI Issues — Root Causes, Verified Fixes, and Suggested Official Solutions (v3.6.11)
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/40 | Three Dashboard UI Issues — Root Causes, Verified Fixes, and Suggested Official Solutions (v3.6.11)

12. 安装坑 · 失败模式：installation: bug: metrics flush loop constructs a new CacheDB every 60s, logging spurious 'Schema initiali...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: bug: metrics flush loop constructs a new CacheDB every 60s, logging spurious 'Schema initialized' and re-deriving AES key on each tick
• 对用户的影响：Developers may fail before the first successful local run: bug: metrics flush loop constructs a new CacheDB every 60s, logging spurious 'Schema initialized' and re-deriving AES key on each tick
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/48 | bug: metrics flush loop constructs a new CacheDB every 60s, logging spurious 'Schema initialized' and re-deriving AES key on each tick

13. 安装坑 · 失败模式：installation: esh_summary causes daemon crash — heartbeat_active: false and immediate shutdown

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: esh_summary causes daemon crash — heartbeat_active: false and immediate shutdown
• 对用户的影响：Developers may fail before the first successful local run: esh_summary causes daemon crash — heartbeat_active: false and immediate shutdown
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/34 | esh_summary causes daemon crash — heartbeat_active: false and immediate shutdown, failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/34 | esh_summary causes daemon crash — heartbeat_active: false and immediate shutdown

14. 安装坑 · 失败模式：installation: installation with claude on ubuntu 22.04 LTS

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: installation with claude on ubuntu 22.04 LTS
• 对用户的影响：Developers may fail before the first successful local run: installation with claude on ubuntu 22.04 LTS
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/32 | installation with claude on ubuntu 22.04 LTS

15. 安装坑 · 失败模式：installation: start session with claude not creating a sessionid

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: start session with claude not creating a sessionid
• 对用户的影响：Developers may fail before the first successful local run: start session with claude not creating a sessionid
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/35 | start session with claude not creating a sessionid

16. 安装坑 · 失败模式：installation: v3.6.10: Three Remaining Frontend/Auth Issues in Distributed LAN Deployments

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v3.6.10: Three Remaining Frontend/Auth Issues in Distributed LAN Deployments
• 对用户的影响：Developers may fail before the first successful local run: v3.6.10: Three Remaining Frontend/Auth Issues in Distributed LAN Deployments
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/39 | v3.6.10: Three Remaining Frontend/Auth Issues in Distributed LAN Deployments

17. 安装坑 · 失败模式：installation: v3.6.12: SLM_REMOTE=1 partially working — /internal/token still returns 403

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v3.6.12: SLM_REMOTE=1 partially working — /internal/token still returns 403
• 对用户的影响：Developers may fail before the first successful local run: v3.6.12: SLM_REMOTE=1 partially working — /internal/token still returns 403
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/41 | v3.6.12: SLM_REMOTE=1 partially working — /internal/token still returns 403

18. 安装坑 · 来源证据：Cognitive consolidation and trace issues on Linux/Docker setup

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Cognitive consolidation and trace issues on Linux/Docker setup
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/26 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 安装坑 · 来源证据：Feature: Have opening and closing sessions available as direct calls on top of the existing MCP tool calls

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Have opening and closing sessions available as direct calls on top of the existing MCP tool calls
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/49 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

20. 安装坑 · 来源证据：SQLite database is locked under sustained concurrent writes — suggest exposing DB lock parameters as environment variab…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：SQLite database is locked under sustained concurrent writes — suggest exposing DB lock parameters as environment variables, and a longer-term thought on PGLite
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/53 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

21. 安装坑 · 来源证据：base_dir in config.json is ignored by SLMConfig.load() and not persisted by save()

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：base_dir in config.json is ignored by SLMConfig.load() and not persisted by save()
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/28 | 来源类型 github_issue 暴露的待验证使用条件。

22. 安装坑 · 来源证据：bug: metrics flush loop constructs a new CacheDB every 60s, logging spurious 'Schema initialized' and re-deriving AES k…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: metrics flush loop constructs a new CacheDB every 60s, logging spurious 'Schema initialized' and re-deriving AES key on each tick
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/48 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

23. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/qualixar/superlocalmemory | host_targets=mcp_host, claude_code, claude, cursor

24. 配置坑 · 失败模式：configuration: Distributed deployment feedback + OpenClaw plugin suggestion

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Distributed deployment feedback + OpenClaw plugin suggestion
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Distributed deployment feedback + OpenClaw plugin suggestion
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/46 | Distributed deployment feedback + OpenClaw plugin suggestion, failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/46 | Distributed deployment feedback + OpenClaw plugin suggestion

25. 配置坑 · 失败模式：configuration: RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/20 | RFC: Multi-Scope Memory — personal/global/shared scopes with scope-aware retrieval

26. 配置坑 · 失败模式：configuration: Request: Document all supported environment variables and config keys

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Request: Document all supported environment variables and config keys
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Request: Document all supported environment variables and config keys
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/37 | Request: Document all supported environment variables and config keys, failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/37 | Request: Document all supported environment variables and config keys

27. 配置坑 · 来源证据：Distributed deployment: mcp/server.py get_engine() deadlocks daemon with sqlite3.OperationalError

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Distributed deployment: mcp/server.py get_engine() deadlocks daemon with sqlite3.OperationalError
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/59 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

28. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/qualixar/superlocalmemory | README/documentation is current enough for a first validation pass.

29. 维护坑 · 失败模式：migration: bug: BackendOrchestrator uses DatabaseManager "conn" attribute which doesn't exist, silently...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: bug: BackendOrchestrator uses DatabaseManager "conn" attribute which doesn't exist, silently breaking schema v3.4.5 migration on every boot
• 对用户的影响：Developers may hit a documented source-backed failure mode: bug: BackendOrchestrator uses DatabaseManager "conn" attribute which doesn't exist, silently breaking schema v3.4.5 migration on every boot
• 证据：failure_mode_cluster:github_issue | https://github.com/qualixar/superlocalmemory/issues/47 | bug: BackendOrchestrator uses DatabaseManager "conn" attribute which doesn't exist, silently breaking schema v3.4.5 migration on every boot

30. 维护坑 · 来源证据：can you share from where you too python code fro xMemory (Stanford) → Identity pattern learning

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：can you share from where you too python code fro xMemory (Stanford) → Identity pattern learning
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

31. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/qualixar/superlocalmemory | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/qualixar/superlocalmemory | no_demo; severity=medium

33. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/qualixar/superlocalmemory | no_demo; severity=medium

34. 安全/权限坑 · 来源证据：GitHub issue body — qualixar SLM_HOST feature request

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GitHub issue body — qualixar SLM_HOST feature request
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/23 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

35. 安全/权限坑 · 来源证据：SLM_REMOTE=1 does not allow HTTP MCP connections from LAN containers (421 Misdirected Request persists)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：SLM_REMOTE=1 does not allow HTTP MCP connections from LAN containers (421 Misdirected Request persists)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/45 | 来源类型 github_issue 暴露的待验证使用条件。

36. 安全/权限坑 · 来源证据：[BUG] Web UI blocks unauthenticated local llama.cpp endpoints under OpenAI provider

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Web UI blocks unauthenticated local llama.cpp endpoints under OpenAI provider
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/29 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

37. 安全/权限坑 · 来源证据：v3.6.10: Three Remaining Frontend/Auth Issues in Distributed LAN Deployments

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v3.6.10: Three Remaining Frontend/Auth Issues in Distributed LAN Deployments
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/qualixar/superlocalmemory/issues/39 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

38. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/qualixar/superlocalmemory | issue_or_pr_quality=unknown

39. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/qualixar/superlocalmemory | release_recency=unknown