项目定位与核心能力

local-memory-mcp 是一个本地化的 Model Context Protocol（MCP）服务器，目标是为 LLM 代理提供持久化的记忆、代码库索引、任务管理与可视化能力。系统以单进程方式运行，所有数据落地在本地 SQLite 数据库中，避免外部服务依赖，便于在受限环境（CI、个人开发机、离线工作流）下使用。

主要项目括：

• 结构化记忆：以 memories、coding_standards、code_patterns、tools 等实体形式保存项目专属知识。
• 代码库索引：通过 tree-sitter 解析主流语言，构建可被代理检索的符号图谱。
• 任务与回放：提供 tasks、task_comments、action_log 等用于协作追踪与操作审计。
• 仪表板：基于 Express 的可视化界面，支持导出、检索、知识图谱查看。
• 向量检索：内置 StubVectorStore 与 RealVectorStore（基于 Xenova/all-MiniLM-L6-v2 ONNX 模型）两套实现。

资料来源：README.md:1-40，package.json:1-60

技术栈与关键决策

系统基于 Node.js + TypeScript，使用 SQLite 作为唯一持久层。这一选择在 ADR 中被明确记录：

"SQLite 提供零运维、嵌入式事务与单文件备份能力，契合本地化运行目标。"

辅助技术包括：

• proper-lockfile 提供跨进程文件锁，串行化写工具调用。
• tree-sitter WASM 在 Node 端完成多语言语法解析。
• @huggingface/transformers（transformers.js）负责向量化。
• express + ws 提供仪表板 HTTP / WebSocket。

资料来源：.agents/documents/design/decisions/adr-001-use-sqlite.md:1-30，.agents/documents/design/decisions/adr-002-codebase-index.md:1-40

模块划分与请求流

代码在 src/ 下划分为四个主要子系统：

一次典型的工具调用流程为：客户端 → router.ts 解析会话与作用域 → tools/index.ts 归一化参数 → 实体层执行业务逻辑 → 存储层加锁落库 → 返回结果。下图给出请求在子系统间的流转。

flowchart LR
  Client[MCP 客户端] --> Router[router.ts]
  Router --> Tools[tools/index.ts]
  Tools --> Entities[entities/*]
  Entities --> Storage[storage/*]
  Storage --> SQLite[(SQLite)]
  Storage --> Vectors[VectorStore]
  Entities --> Dashboard[dashboard/*]

资料来源：.agents/documents/design/architecture/architecture.md:1-80，package.json:30-90

当前状态与已知问题

当前发布版本为 v0.23.0，CHANGELOG 显示近期主要工作是完善工具路由与代码库索引的稳定性。社区反馈集中在性能与一致性，已被记录为多项 issue：

• 写工具锁竞争：memory-acknowledge、incrementHitCount 等频繁触发文件锁。资料来源：src/mcp/tools/index.ts:83-116
• SQLite 缺少 (owner, repo) 组合索引，导致按仓库查询走全表扫描。资料来源：src/mcp/storage/migrations.ts:1-60
• ONNX 模型懒加载存在首请求超时风险。资料来源：src/mcp/storage/vectors.ts:28-33
• tree-sitter 全部 13 个 WASM 在启动时并发加载，造成 30MB+ 内存浪费。资料来源：src/mcp/codebase-index/parser/parser-pool.ts:206-289

这些问题构成了下一阶段重构（路由去重、向量化懒加载、索引优化、文件发现并行化）的核心议程。

资料来源：CHANGELOG.md:1-40

概述

local-memory-mcp 是一个基于 Model Context Protocol (MCP) 协议的本地记忆服务器，向 LLM 客户端暴露一组结构化的记忆、任务与知识图谱工具。核心目标是为 AI 代理提供一个持久化、可检索、带语义去重的本地知识库，覆盖三种实体类型：

• Memory：项目级或全局级的事实、偏好、决策记录。
• Task / TaskComment：任务流转与协作评论。
• Knowledge Graph（KG）实体与关系：显式建模的实体-关系三元组，可被外部工具查询或可视化。

服务器通过 router.ts 统一接收 JSON-RPC 请求，将其分派到 tools/index.ts 中注册的处理器，并最终调用对应实体的业务逻辑（src/mcp/entities/*）以及存储适配层（src/mcp/storage/*）。

MCP 服务器与路由

src/mcp/router.ts 是服务器入口，处理 JSON-RPC 帧、session 注入、scope 解析与 root-bound 路径校验。其内部的 normalizeToolArguments（约 80 行）负责从 session 中补充 owner/repo、解析作用域并校验调用方路径是否落在允许的根目录下 资料来源：src/mcp/router.ts:387-473。

该函数在 src/mcp/tools/index.ts:133-242 中存在近重复实现，仅在变量命名上略有差异 资料来源：src/mcp/tools/index.ts:133-242。issue #54 提出需要将这段逻辑提取到共享模块以避免行为漂移。

工具调用根据读写语义被划分为两组，定义于 WRITE_TOOLS 常量集中：

写工具的锁竞争问题已在 issue #47 中记录，热路径上诸如 memory-acknowledge 与 incrementHitCount 会成为瓶颈 资料来源：src/mcp/tools/index.ts:83-116。

记忆工具（Memory Tools）

记忆工具的定义集中在 src/mcp/tools/definitions/memory.ts，覆盖 memory-store、memory-recall、memory-search、memory-update、memory-archive 等核心操作。每个工具在注册时由 tools/index.ts 包装为统一的处理器，并强制经过 normalizeToolArguments 做参数归一化。

存储层使用 SQLite，迁移脚本位于 src/mcp/storage/migrations.ts。当前迁移为 memories(repo)、tasks(repo)、action_log(repo) 等单列索引，但绝大多数查询同时按 owner 与 repo 过滤，导致只能命中其中一个索引，其余条件退化为扫描——issue #49 已建议补充 (owner, repo) 复合索引 资料来源：src/mcp/storage/migrations.ts。

向量化检索默认走 RealVectorStore（src/mcp/storage/vectors.ts），懒加载 Xenova/all-MiniLM-L6-v2 ONNX 模型；测试或受限环境可切到 StubVectorStore（src/mcp/storage/vectors.stub.ts），后者在 upsert() 阶段将 token 直接置零，搜索时重新构建 TF-IDF 向量（issue #55） 资料来源：src/mcp/storage/vectors.ts:28-33、资料来源：src/mcp/storage/vectors.stub.ts:62-135。

StandardEntity.search()（src/mcp/entities/standard.ts:90-152）当前通过 LIKE '%term%' 在 title/content/context 上做全文匹配，无法命中索引；issue #53 建议改用 SQLite FTS5 虚拟表以避免全表扫描 资料来源：src/mcp/entities/standard.ts:90-152。checkConflicts()（同文件 214–260 行）在一次调用中既调用 searchBySimilarity() 又二次遍历候选并重复计算 cosine 相似度，issue #56 已指出可合并为单次遍历 资料来源：src/mcp/entities/standard.ts:214-260。

任务与知识图谱

src/mcp/tools/definitions/task.ts 定义任务相关工具（task-create、task-comment-add、task-status-update 等），与记忆工具共享相同的归一化与锁定流程。任务评论通过 taskComments 表与 tasks 表通过 task_id 外键关联。

src/mcp/tools/definitions/knowledge-graph.ts 暴露 KG 操作：kg-add-entity、kg-add-relation、kg-query、kg-subgraph 等。KG 数据与记忆/任务一起持久化到同一 SQLite 数据库；issue #58 计划将前端 KG 标签页升级为统一的力导向图，把记忆、代码符号、任务以神经网络风格可视化 资料来源：src/mcp/tools/definitions/knowledge-graph.ts。

下图为典型调用流：

flowchart LR
  Client[MCP 客户端] -->|JSON-RPC| Router[router.ts]
  Router -->|normalize| Tools[tools/index.ts]
  Tools --> M[memory.ts]
  Tools --> T[task.ts]
  Tools --> KG[knowledge-graph.ts]
  M --> Ent[entities/standard.ts]
  T --> Ent
  KG --> Ent
  Ent --> DB[(SQLite)]
  Ent --> VS{VectorStore}
  VS -->|真实| Real[vectors.ts + ONNX]
  VS -->|桩| Stub[vectors.stub.ts]

已知约束与改进方向

综合社区反馈（issue #47–58），当前子系统面临的主要问题包括：写工具文件锁竞争、(owner, repo) 复合索引缺失、LIKE '%term%' 全文检索、StandardEntity.checkConflicts 重复计算、桩向量库零向量冗余、ONNX 模型懒加载阻塞首请求以及 normalizeToolArguments 在两处复制。修复后可显著降低 P99 延迟并提升大仓库下的索引吞吐。

系统概述与定位

src/mcp/codebase-index/ 子系统负责将本地代码仓库转换为可被 MCP 工具检索的结构化知识。它由两层协作组件构成：

1. 文件发现层（services/file-discovery.ts）扫描仓库文件系统，过滤被 .gitignore 忽略的文件，并将候选文件交给下游。
2. 树解析层（parser/）使用 tree-sitter WASM 语法为每种语言构建 AST，并通过 Visitor 模式抽取函数、类、变量、Markdown 标题等结构化实体。

索引产物最终写入存储层（SQLite + 向量库），供 codebase_search、codebase_lookup 等 MCP 工具在会话中按符号名或语义相似度进行检索。

文件发现服务

file-discovery.ts 的核心职责是枚举仓库内可索引的文件。已知的两个关键行为直接影响大仓库的索引吞吐：

• 仅在启动时读取根级 .gitignore，子目录中的 .gitignore（例如 monorepo 中 packages/foo/.gitignore）不被尊重，导致已被 Git 忽略的文件被错误纳入索引。 资料来源：src/mcp/codebase-index/services/file-discovery.ts:124-134
• 文件元数据查询使用同步的 fs.lstatSync，且并发度受限，在大型仓库中会产生 5–10 倍的索引延迟。 资料来源：src/mcp/codebase-index/services/file-discovery.ts:124-134

这两点已在社区 issue #57 与 #51 中被记录，是当前文件发现层最主要的瓶颈。

Tree-sitter 解析器池

parser-pool.ts 实现 TreeSitterParserPool，统一管理多语言 tree-sitter 解析器。_doInitialize() 在进程启动时通过 Promise.allSettled() 并行加载全部 13 种语言的 WASM 语法：

C、C++、Dart、Go、Java、JavaScript、Kotlin、PHP、Python、Ruby、Rust、Swift、TypeScript

每个 WASM 二进制约 2–3 MB，合计超过 30 MB 的初始内存开销，且对未使用语言也强制加载。社区已记录该行为（issue #50），建议改为按需懒加载。 资料来源：src/mcp/codebase-index/parser/parser-pool.ts:206-289

池对外暴露统一的 parse(filePath, source) 接口，根据扩展名分发到对应语言的 Parser，并对生成的 CST 树做短期缓存以减少重复解析。

AST 访问器与实体抽取

CST 树被路由到语言专用的 Visitor，再归一化为统一的 CodeEntity：

parser/index.ts 是调度入口，根据扩展名选择 Visitor 并返回 CodeEntity[]。该层将不同语言的抽象语法树归一化为知识图谱节点，是后续向量嵌入与符号检索的基础。 资料来源：src/mcp/codebase-index/parser/index.ts

通过统一实体模型，codebase_search 工具可跨语言执行「按符号名检索 + 上下文回溯」，结合向量相似度返回相关代码片段。

当前局限与改进方向

这些优化将使代码库索引在大型 monorepo 上的首次扫描与增量更新都获得显著加速，并降低冷启动期间的内存峰值。

local-memory-mcp 通过 src/dashboard/ 提供基于 Svelte 的可视化层，使用 SQLite 作为主要持久化后端，并通过 src/mcp/storage/ 子系统管理连接、迁移、向量存储与写入锁。本页梳理仪表板、SQLite 存储及其已知性能瓶颈与优化路径，涵盖社区近期重点关注的多项议题（#47、#48、#49、#50、#51、#52、#53、#55、#57、#58）。

系统分层与存储基础

存储子系统由 base.ts 定义抽象接口（行级 CRUD、事务、批量写入），并由 sqlite.ts 实现具体驱动；启动时通过 migrations.ts 顺序执行 schema 升级。基础抽象层将仪表板读写与 MCP 工具读写统一在同一个 Base 实例上，从而保证两边对一致性的视图。

仪表板层的 SystemController.getExport() 是消费完整数据库的关键节点。导出流程会调用 db.memories.getAllMemoriesWithStats("", repo)、db.tasks.getTasksByRepo("", repo)、db.taskComments.getAllTaskComments() 等聚合接口，将所有行加载至内存后再生成 JSON。这与 sqlite.ts 的 getAll* 方法直接对应，是 #48 提到的 OOM 风险源头。

资料来源：src/mcp/storage/base.ts:1-80、src/mcp/storage/sqlite.ts:1-120、src/dashboard/controllers/SystemController.ts:142-177。

SQLite 索引与查询优化

migrations.ts 当前仅在 memories(repo)、tasks(repo)、action_log(repo) 等列上创建单列索引，而绝大多数 MCP 工具与仪表板查询都会同时过滤 owner 与 repo。SQLite 只能使用其中一个索引，导致在多租户场景下出现全表扫描，#49 即针对该缺陷提出增加 (owner, repo) 复合索引的方案。

搜索路径同样存在性能缺陷：StandardEntity.search() 在 title、content、context 上使用 WHERE … LIKE '%term%'，SQLite 的前导通配符 LIKE 无法走索引，触发顺序扫描。修复方案是引入 FTS5 虚拟表，并将 LIKE 路径替换为 FTS5 的 MATCH 表达式（#53）。

资料来源：src/mcp/storage/migrations.ts:1-160、src/mcp/entities/standard.ts:90-152。

向量存储与延迟初始化

向量存储提供两套实现：vectors.ts 是基于 Xenova/all-MiniLM-L6-v2 ONNX 模型的真实向量库；vectors.stub.ts 则是仅做分词的桩实现，用于测试和零依赖环境。vectors.ts 的 initialize() 异步触发 getExtractor() 但不 await，首请求到达时仍可能命中模型加载窗口，#52 建议将首次调用显式阻塞或预热。

vectors.stub.ts 的 upsert() 先 tokenize，再以 tokens.map(() => 0) 存入零向量；search() 又从文本重新计算 TF-IDF 频率向量。这导致写入的零向量与读取的频率向量语义不一致、且搜索时存在重复计算，#55 建议改为持久化真实向量或缓存哈希键。

资料来源：src/mcp/storage/vectors.ts:28-120、src/mcp/storage/vectors.stub.ts:62-135。

写入锁、解析池与文件扫描

write-lock.ts 使用 proper-lockfile 提供进程间文件锁，默认 250 次重试 × 200ms = 50s 最长等待。memory-acknowledge、incrementHitCount、incrementRecallCount 等高频写工具被列入 WRITE_TOOLS，每次调用都要排队获取锁，#47 指出可拆分为命中计数器专属的轻量锁或行级乐观更新。

TreeSitterParserPool._doInitialize() 在启动阶段通过 Promise.allSettled() 并发加载全部 13 个语言（C、C++、Dart、Go、Java、JavaScript、Kotlin、PHP、Python、Ruby、Rust、Swift、TypeScript）的 WASM 语法包，常驻内存约 30MB+，#50 建议改为按语言懒加载，仅在首次解析该语言文件时再请求 WASM。

codebase-index/services/file-discovery.ts 在递归扫描时使用 fs.lstatSync 与较低的并发度，#51 指出应改用 fs.promises.lstat 并结合 p-limit 提高并发。同时该文件只读取仓库根级 .gitignore，子目录内的 packages/foo/.gitignore 被忽略，#57 建议在每个目录递归检查并合并规则。

资料来源：src/mcp/storage/write-lock.ts:1-80、src/mcp/codebase-index/parser/parser-pool.ts:206-289、src/mcp/codebase-index/services/file-discovery.ts:124-134。

仪表板可视化演进

仪表板当前依赖知识图谱（KG）页签展示实体关系。#58 提出将其升级为统一的力导向图，将 memories、codebase symbols、tasks 渲染为互联节点，形成类似神经网络的可视化，从而把存储、检索、任务执行三类对象映射到同一画布，便于在大规模数据下人工排查关系密度与热点节点。

总体来看，v0.23.0 的优化重点集中在「减少全表扫描」「拆解串行锁」「延迟重型资源」与「流式仪表板导出」四个方向，可作为后续 PR 的优先级参考。

Pitfall Log / 踩坑日志

项目：vheins/local-memory-mcp

摘要：发现 37 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: feat: full-local natural language codebase search (codebase_search tool)。

1. 安装坑 · 失败模式：installation: feat: full-local natural language codebase search (codebase_search tool)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: feat: full-local natural language codebase search (codebase_search tool)
• 对用户的影响：Developers may fail before the first successful local run: feat: full-local natural language codebase search (codebase_search tool)
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/45 | feat: full-local natural language codebase search (codebase_search tool)

2. 安装坑 · 失败模式：installation: feat: tambahkan monorepo workspace seperti turbo repo

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: feat: tambahkan monorepo workspace seperti turbo repo
• 对用户的影响：Developers may fail before the first successful local run: feat: tambahkan monorepo workspace seperti turbo repo
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/42 | feat: tambahkan monorepo workspace seperti turbo repo

3. 安装坑 · 失败模式：installation: perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste
• 对用户的影响：Developers may fail before the first successful local run: perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/50 | perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste

4. 安装坑 · 来源证据：feat: full-local natural language codebase search (codebase_search tool)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: full-local natural language codebase search (codebase_search tool)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/45 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：fix: nested .gitignore not respected during file discovery

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: nested .gitignore not respected during file discovery
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/57 | 来源类型 github_issue 暴露的待验证使用条件。

6. 安装坑 · 来源证据：perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/51 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/50 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

9. 配置坑 · 失败模式：configuration: feat: unified neural network graph for memory, codebase, and task visualization

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: feat: unified neural network graph for memory, codebase, and task visualization
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat: unified neural network graph for memory, codebase, and task visualization
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/58 | feat: unified neural network graph for memory, codebase, and task visualization

10. 配置坑 · 失败模式：configuration: perf: missing composite indexes on (owner, repo) — full table scans on frequent queries

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: perf: missing composite indexes on (owner, repo) — full table scans on frequent queries
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: perf: missing composite indexes on (owner, repo) — full table scans on frequent queries
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/49 | perf: missing composite indexes on (owner, repo) — full table scans on frequent queries

11. 配置坑 · 失败模式：configuration: v0.20.4 — Multi-language Parsing

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.20.4 — Multi-language Parsing
• 对用户的影响：Upgrade or migration may change expected behavior: v0.20.4 — Multi-language Parsing
• 证据：failure_mode_cluster:github_release | https://github.com/vheins/local-memory-mcp/releases/tag/v0.20.4 | v0.20.4 — Multi-language Parsing

12. 配置坑 · 来源证据：perf: dashboard export loads entire DB into memory — OOM risk

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：perf: dashboard export loads entire DB into memory — OOM risk
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/48 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

13. 配置坑 · 来源证据：perf: missing composite indexes on (owner, repo) — full table scans on frequent queries

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：perf: missing composite indexes on (owner, repo) — full table scans on frequent queries
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/49 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

15. 运行坑 · 来源证据：fix: double vector computation in StandardEntity.checkConflicts

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix: double vector computation in StandardEntity.checkConflicts
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/56 | 来源类型 github_issue 暴露的待验证使用条件。

16. 运行坑 · 来源证据：perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/52 | 来源类型 github_issue 暴露的待验证使用条件。

17. 运行坑 · 来源证据：perf: search_symbols loads ALL symbols into memory — OOM risk on large repos

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：perf: search_symbols loads ALL symbols into memory — OOM risk on large repos
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/46 | 来源类型 github_issue 暴露的待验证使用条件。

18. 运行坑 · 来源证据：refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/54 | 来源类型 github_issue 暴露的待验证使用条件。

19. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/vheins/local-memory-mcp | matched external service / cloud / webhook / database keyword

20. 维护坑 · 失败模式：migration: perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search
• 对用户的影响：Developers may hit a documented source-backed failure mode: perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/53 | perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search

21. 维护坑 · 失败模式：migration: v0.21.0 — Codebase Search NL + FTS5 Standards

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.21.0 — Codebase Search NL + FTS5 Standards
• 对用户的影响：Upgrade or migration may change expected behavior: v0.21.0 — Codebase Search NL + FTS5 Standards
• 证据：failure_mode_cluster:github_release | https://github.com/vheins/local-memory-mcp/releases/tag/v0.21.0 | v0.21.0 — Codebase Search NL + FTS5 Standards

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/vheins/local-memory-mcp | no_demo; severity=medium

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

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

25. 安全/权限坑 · 来源证据：feat: unified neural network graph for memory, codebase, and task visualization

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: unified neural network graph for memory, codebase, and task visualization
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/58 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

26. 安全/权限坑 · 来源证据：perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/55 | 来源类型 github_issue 暴露的待验证使用条件。

27. 安全/权限坑 · 来源证据：perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/53 | 来源类型 github_issue 暴露的待验证使用条件。

28. 运行坑 · 失败模式：performance: fix: double vector computation in StandardEntity.checkConflicts

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: fix: double vector computation in StandardEntity.checkConflicts
• 对用户的影响：Developers may hit a documented source-backed failure mode: fix: double vector computation in StandardEntity.checkConflicts
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/56 | fix: double vector computation in StandardEntity.checkConflicts

29. 运行坑 · 失败模式：performance: fix: nested .gitignore not respected during file discovery

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: fix: nested .gitignore not respected during file discovery
• 对用户的影响：Developers may hit a documented source-backed failure mode: fix: nested .gitignore not respected during file discovery
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/57 | fix: nested .gitignore not respected during file discovery

30. 运行坑 · 失败模式：performance: perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk
• 对用户的影响：Developers may hit a documented source-backed failure mode: perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/52 | perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk

31. 运行坑 · 失败模式：performance: perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search
• 对用户的影响：Developers may hit a documented source-backed failure mode: perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/55 | perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search

32. 运行坑 · 失败模式：performance: perf: dashboard export loads entire DB into memory — OOM risk

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: perf: dashboard export loads entire DB into memory — OOM risk
• 对用户的影响：Developers may hit a documented source-backed failure mode: perf: dashboard export loads entire DB into memory — OOM risk
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/48 | perf: dashboard export loads entire DB into memory — OOM risk

33. 运行坑 · 失败模式：performance: perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline
• 对用户的影响：Developers may hit a documented source-backed failure mode: perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/51 | perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline

34. 运行坑 · 失败模式：performance: perf: write lock contention on memory-acknowledge and hit-count tools

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: perf: write lock contention on memory-acknowledge and hit-count tools
• 对用户的影响：Developers may hit a documented source-backed failure mode: perf: write lock contention on memory-acknowledge and hit-count tools
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/47 | perf: write lock contention on memory-acknowledge and hit-count tools

35. 运行坑 · 失败模式：performance: refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts
• 对用户的影响：Developers may hit a documented source-backed failure mode: refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts
• 证据：failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/54 | refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts

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

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

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

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