# https://github.com/vheins/local-memory-mcp 项目说明书

生成时间：2026-07-25 10:21:26 UTC

## 目录

- [项目概述与整体架构](#page-1)
- [MCP 服务器、记忆工具与知识图谱](#page-2)
- [代码库索引系统与树解析检索](#page-3)
- [Svelte 仪表板、SQLite 存储与性能优化](#page-4)

<a id='page-1'></a>

## 项目概述与整体架构

### 相关页面

相关主题：[MCP 服务器、记忆工具与知识图谱](#page-2), [Svelte 仪表板、SQLite 存储与性能优化](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/vheins/local-memory-mcp/blob/main/README.md)
- [package.json](https://github.com/vheins/local-memory-mcp/blob/main/package.json)
- [CHANGELOG.md](https://github.com/vheins/local-memory-mcp/blob/main/CHANGELOG.md)
- [.agents/documents/design/architecture/architecture.md](https://github.com/vheins/local-memory-mcp/blob/main/.agents/documents/design/architecture/architecture.md)
- [.agents/documents/design/decisions/adr-001-use-sqlite.md](https://github.com/vheins/local-memory-mcp/blob/main/.agents/documents/design/decisions/adr-001-use-sqlite.md)
- [.agents/documents/design/decisions/adr-002-codebase-index.md](https://github.com/vheins/local-memory-mcp/blob/main/.agents/documents/design/decisions/adr-002-codebase-index.md)
</details>

# 项目概述与整体架构

## 项目定位与核心能力

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/` 下划分为四个主要子系统：

| 子系统 | 路径 | 职责 |
| --- | --- | --- |
| MCP 服务 | `src/mcp/` | 工具注册、路由、会话解析、参数归一化 |
| 存储层 | `src/mcp/storage/` | SQLite migrations、向量存储、文件锁 |
| 实体层 | `src/mcp/entities/` | 业务模型、相似度检索、冲突检测 |
| 仪表板 | `src/dashboard/` | HTTP 控制器、视图、知识图谱渲染 |

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

```mermaid
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]()

---

<a id='page-2'></a>

## MCP 服务器、记忆工具与知识图谱

### 相关页面

相关主题：[项目概述与整体架构](#page-1), [Svelte 仪表板、SQLite 存储与性能优化](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/router.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/router.ts)
- [src/mcp/tools/index.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/tools/index.ts)
- [src/mcp/tools/definitions/memory.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/tools/definitions/memory.ts)
- [src/mcp/tools/definitions/task.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/tools/definitions/task.ts)
- [src/mcp/tools/definitions/standard.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/tools/definitions/standard.ts)
- [src/mcp/tools/definitions/knowledge-graph.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/tools/definitions/knowledge-graph.ts)
- [src/mcp/entities/standard.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/standard.ts)
- [src/mcp/storage/vectors.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/vectors.ts)
- [src/mcp/storage/vectors.stub.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/vectors.stub.ts)
- [src/mcp/storage/migrations.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/migrations.ts)
</details>

# MCP 服务器、记忆工具与知识图谱

## 概述

`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` 常量集中：

| 工具类别 | 示例工具 | 同步文件锁 |
|---|---|---|
| 写工具 | `memory-store`、`memory-acknowledge`、`incrementHitCount`、`incrementRecallCount` | `proper-lockfile`，最多重试 250 次（≈ 50s） |
| 读工具 | `memory-recall`、`memory-search`、`kg-query` | 不获取写锁 |

写工具的锁竞争问题已在 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]()。

下图为典型调用流：

```mermaid
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 延迟并提升大仓库下的索引吞吐。

---

<a id='page-3'></a>

## 代码库索引系统与树解析检索

### 相关页面

相关主题：[MCP 服务器、记忆工具与知识图谱](#page-2), [Svelte 仪表板、SQLite 存储与性能优化](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/codebase-index/parser/parser-pool.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/parser/parser-pool.ts)
- [src/mcp/codebase-index/parser/index.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/parser/index.ts)
- [src/mcp/codebase-index/parser/typescript-visitor.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/parser/typescript-visitor.ts)
- [src/mcp/codebase-index/parser/markdown-visitor.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/parser/markdown-visitor.ts)
- [src/mcp/codebase-index/parser/generic-visitor.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/parser/generic-visitor.ts)
- [src/mcp/codebase-index/services/file-discovery.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/services/file-discovery.ts)
</details>

# 代码库索引系统与树解析检索

## 系统概述与定位

`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`：

| Visitor | 适用文件 | 主要抽取目标 |
|---------|----------|--------------|
| `typescript-visitor.ts` | `.ts` / `.js` | 类、方法、接口、类型别名、导出符号 |
| `markdown-visitor.ts` | `.md` | 标题层级、代码块、链接 |
| `generic-visitor.ts` | 兜底 | 基于正则的轻量符号识别 |

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

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

## 当前局限与改进方向

| 问题 | 来源 | 建议方向 |
|------|------|----------|
| 嵌套 `.gitignore` 未生效 | issue #57 | 使用 `ignore` 库或 `git check-ignore` 委派判定 |
| `lstatSync` + 低并发 | issue #51 | 切换 `fs.promises.lstat` 并提升并发上限 |
| 启动期 WASM 整体加载 | issue #50 | 懒加载或预编译缓存 |
| `coding_standards` LIKE 全表扫描 | issue #53 | 升级到 SQLite FTS5 |

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

---

<a id='page-4'></a>

## Svelte 仪表板、SQLite 存储与性能优化

### 相关页面

相关主题：[项目概述与整体架构](#page-1), [MCP 服务器、记忆工具与知识图谱](#page-2), [代码库索引系统与树解析检索](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/storage/base.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/base.ts)
- [src/mcp/storage/sqlite.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/sqlite.ts)
- [src/mcp/storage/migrations.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/migrations.ts)
- [src/mcp/storage/vectors.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/vectors.ts)
- [src/mcp/storage/vectors.stub.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/vectors.stub.ts)
- [src/mcp/storage/write-lock.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/write-lock.ts)
- [src/dashboard/controllers/SystemController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/SystemController.ts)
- [src/mcp/entities/standard.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/standard.ts)
- [src/mcp/codebase-index/parser/parser-pool.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/parser/parser-pool.ts)
- [src/mcp/codebase-index/services/file-discovery.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/services/file-discovery.ts)
</details>

# Svelte 仪表板、SQLite 存储与性能优化

`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 渲染为互联节点，形成类似神经网络的可视化，从而把存储、检索、任务执行三类对象映射到同一画布，便于在大规模数据下人工排查关系密度与热点节点。

| 模块 | 主要文件 | 关键优化方向 |
| --- | --- | --- |
| 存储抽象 | `storage/base.ts`、`storage/sqlite.ts` | 抽象一致性、流式导出 |
| 模式与查询 | `storage/migrations.ts`、`entities/standard.ts` | 复合索引、FTS5 替换 `LIKE '%term%'` |
| 向量存储 | `storage/vectors.ts`、`storage/vectors.stub.ts` | ONNX 预热、持久化真实向量 |
| 并发与解析 | `storage/write-lock.ts`、`parser/parser-pool.ts` | 拆分轻量写锁、懒加载 WASM |
| 索引管线 | `codebase-index/services/file-discovery.ts` | 异步 `lstat`、递归 `.gitignore` |
| 可视化 | `dashboard/controllers/SystemController.ts` | 流式导出、统一力导向图（#58） |

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

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

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

<!-- canonical_name: vheins/local-memory-mcp; human_manual_source: deepwiki_human_wiki -->