# https://github.com/vheins/local-memory-mcp Project Manual Generated at: 2026-07-25 10:23:30 UTC ## Table of Contents - [Overview and System Architecture](#page-1) - [Codebase Index and Source Code Search](#page-2) - [Memory Management, Semantic Search, and Knowledge Graph](#page-3) - [Dashboard UI, Performance, and Operations](#page-4) ## Overview and System Architecture ### Related Pages Related topics: [Codebase Index and Source Code Search](#page-2), [Memory Management, Semantic Search, and Knowledge Graph](#page-3), [Dashboard UI, Performance, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [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) - [bin/mcp-memory-server.js](https://github.com/vheins/local-memory-mcp/blob/main/bin/mcp-memory-server.js) - [bin/mcp-memory-dashboard.js](https://github.com/vheins/local-memory-mcp/blob/main/bin/mcp-memory-dashboard.js) - [src/mcp/server.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/server.ts) - [src/mcp/mcp-server.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/mcp-server.ts) - [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/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/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/dashboard/controllers/SystemController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/SystemController.ts)
# Overview and System Architecture ## Purpose and Scope `local-memory-mcp` is a Model Context Protocol (MCP) server that provides persistent, repository-scoped memory for AI coding assistants. It is shipped as a Node.js package (`bin/mcp-memory-server.js` and `bin/mcp-memory-dashboard.js`) and combines a memory store, a codebase indexer, a vector retrieval layer, and a web dashboard under a single MCP-compatible surface. Source: [README.md:1-40](). The system is designed to serve three audiences simultaneously: (1) AI assistants that call MCP tools, (2) developers who curate coding standards and tasks through the dashboard, and (3) automated indexing pipelines that watch repositories and extract semantic information. The current release (`v0.23.0`) is defined in `package.json` and exposes the package as both an MCP server and a standalone dashboard. Source: [package.json:1-40](). ## High-Level Architecture At runtime the project boots two entry points. The MCP server entry point (`bin/mcp-memory-server.js`) initializes the protocol layer in `src/mcp/server.ts` and `src/mcp/mcp-server.ts`, which together register tools, route requests, and persist state. The dashboard entry point (`bin/mcp-memory-dashboard.js`) starts an HTTP/Web UI served from `src/dashboard/` and shares the same underlying storage. ```mermaid flowchart TB Client[MCP Client / AI Assistant] Dash[Dashboard UI] Server[MCP Server
src/mcp/server.ts] Router[Tool Router
src/mcp/router.ts] Tools[Tool Registry
src/mcp/tools/index.ts] Entities[Entity Layer
src/mcp/entities/] Storage[(SQLite
migrations.ts)] Vectors[Vector Store
vectors.ts / vectors.stub.ts] Indexer[Codebase Indexer
codebase-index/] Parser[Tree-sitter Pool
parser-pool.ts] Client --> Server Dash --> Storage Server --> Router Router --> Tools Tools --> Entities Entities --> Storage Entities --> Vectors Indexer --> Parser Parser --> Storage Tools --> Indexer ``` The router in `src/mcp/router.ts` is the central dispatcher. It normalizes incoming tool arguments, injects `owner`/`repo` context from the active session, validates root-bound paths, and then forwards the call to the matching tool handler. Source: [src/mcp/router.ts:387-473](). The tool registry in `src/mcp/tools/index.ts` mirrors that normalization logic and declares which tool names are read-only versus write tools. Source: [src/mcp/tools/index.ts:83-242](). ## Component Breakdown ### Storage and Migration Layer SQLite is the system of record. Schema evolution is managed in `src/mcp/storage/migrations.ts`, where individual indexes are declared on tables such as `memories`, `tasks`, and `action_log`. The storage layer also exposes typed repositories used by the entity objects. Source: [src/mcp/storage/migrations.ts:1-80](). ### Vector Retrieval Two vector backends are supported. `RealVectorStore` lazily loads the `Xenova/all-MiniLM-L6-v2` ONNX model the first time an embedding is requested, which can delay the first request but avoids cold-start failure when the model is unreachable. Source: [src/mcp/storage/vectors.ts:28-33](). A lightweight `StubVectorStore` is used in tests and offline environments; it tokenizes text and stores zero-filled vectors, recomputing a TF-IDF style frequency vector on each search. Source: [src/mcp/storage/vectors.stub.ts:62-135](). ### Entity Layer Domain objects such as `StandardEntity` wrap the storage repositories. They implement `search()`, `upsert()`, and `checkConflicts()`. The current implementation performs substring matching with `LIKE '%term%'` for coding-standards search and double-computes cosine similarity during conflict detection — both flagged as performance issues in the tracker. Source: [src/mcp/entities/standard.ts:90-260](). ### Codebase Indexing The indexing subsystem in `src/mcp/codebase-index/` discovers files, parses them with tree-sitter, and persists symbols. The `TreeSitterParserPool` eagerly loads grammar WASM binaries for all 13 supported languages at startup, which trades memory for first-query latency. Source: [src/mcp/codebase-index/parser/parser-pool.ts:206-289](). File discovery currently reads only the root `.gitignore`, missing nested rules in monorepos. Source: [src/mcp/codebase-index/services/file-discovery.ts:124-134](). ### Dashboard The dashboard in `src/dashboard/` provides a browser UI for browsing memories, tasks, comments, and the knowledge graph. Its `SystemController.getExport()` aggregates data from the storage repositories, which currently loads full result sets into memory before serializing. Source: [src/dashboard/controllers/SystemController.ts:142-177](). ## Known Architectural Concerns The community tracker documents several structural issues that a new contributor should be aware of. `normalizeToolArguments` is duplicated between the router and the tool registry, inviting drift. Source: [src/mcp/router.ts:387-473](), [src/mcp/tools/index.ts:133-242](). Write tools such as `memory-acknowledge`, `incrementHitCount`, and `incrementRecallCount` acquire an inter-process `proper-lockfile` lock for every call, which serializes high-frequency read-modify-write traffic. Source: [src/mcp/tools/index.ts:83-116](). The schema lacks composite `(owner, repo)` indexes even though almost every query filters by both columns. Source: [src/mcp/storage/migrations.ts:1-80](). Finally, a planned evolution replaces the current Knowledge Graph tab with a unified force-directed graph connecting memories, codebase symbols, and tasks as a single neural-network-style visualization. Source: [README.md:1-40](). Together, these signals describe a layered, tool-driven architecture whose boundaries are stable but whose inner layers (storage indexing, vector math, parser warm-up, lock contention) are the primary targets for future refactors. --- ## Codebase Index and Source Code Search ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Memory Management, Semantic Search, and Knowledge Graph](#page-3), [Dashboard UI, Performance, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [src/mcp/codebase-index/cli.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/cli.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) - [src/mcp/codebase-index/services/indexing-service.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/services/indexing-service.ts) - [src/mcp/codebase-index/services/architecture-service.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/services/architecture-service.ts) - [src/mcp/codebase-index/services/trace-service.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/services/trace-service.ts) - [src/mcp/codebase-index/services/symbol-ranking.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/codebase-index/services/symbol-ranking.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)
# Codebase Index and Source Code Search The Codebase Index module turns a target repository into a queryable, symbol-aware knowledge structure that the MCP server exposes to agents and the dashboard. It walks the filesystem, parses source files with tree-sitter, extracts symbols and references, embeds them into a vector store, and supports search and trace queries over the resulting graph. ## Module Layout and Entry Points The module lives under `src/mcp/codebase-index/` and is split into three layers: - **CLI layer** — `cli.ts` is the standalone command entry used to drive indexing from the shell. - **Service layer** — `services/` contains the long-running workers: `file-discovery.ts` for walking the repo, `indexing-service.ts` for orchestrating parsing and persistence, `architecture-service.ts` for high-level structural views, `trace-service.ts` for call/reference traversal, and `symbol-ranking.ts` for ordering search hits. - **Parser layer** — `parser/parser-pool.ts` manages the tree-sitter WASM grammars and their per-language parsers. The CLI and the MCP tool surface both delegate to the services, so the same pipeline backs ad-hoc `index` runs and the interactive search tools. ## Indexing Pipeline The pipeline has four stages: discovery, parsing, extraction, and embedding/persistence. ```mermaid flowchart LR A[cli.ts / tool call] --> B[file-discovery.ts
walk + .gitignore] B --> C[parser-pool.ts
tree-sitter WASM] C --> D[indexing-service.ts
extract symbols/refs] D --> E[VectorStore + SQLite
symbols, files, edges] E --> F[architecture-service.ts
trace-service.ts
symbol-ranking.ts] F --> G[Search / Trace / KG tools] ``` 1. **File discovery** — `file-discovery.ts` walks the target tree and applies ignore rules. As of the current code it only consults the repository-root `.gitignore` (lines 124–134), which causes nested `.gitignore` files inside monorepo sub-packages to be missed. Source: [src/mcp/codebase-index/services/file-discovery.ts:124-134]() 2. **Parsing** — `parser-pool.ts::_doInitialize()` eagerly loads all 13 supported language grammars via `Promise.allSettled()` (lines 206–289). Languages covered are C, C++, Dart, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift, and TypeScript. Source: [src/mcp/codebase-index/parser/parser-pool.ts:206-289]() 3. **Indexing** — `indexing-service.ts` coordinates per-file extraction, builds the symbol table, edges between definitions and references, and pushes rows plus embeddings into storage. 4. **Search and analysis** — `architecture-service.ts`, `trace-service.ts`, and `symbol-ranking.ts` read back the index to answer queries. `symbol-ranking.ts` orders hits using a mix of textual match, recency, and graph proximity rather than raw vector similarity alone. ## Search Surface Once indexed, the module exposes three logical capabilities to MCP consumers: - **Symbol search** — find declarations by name or qualified path; results are ranked by `symbol-ranking.ts`. - **Architecture queries** — answered by `architecture-service.ts`, which summarizes modules, layers, and dependency direction over the indexed graph. - **Reference tracing** — `trace-service.ts` walks caller/callee and import edges starting from a symbol or file, returning the surrounding call graph. Embeddings come from `RealVectorStore` (`Xenova/all-MiniLM-L6-v2` ONNX model), which is instantiated lazily on the first embedding request and may briefly block the first search. Source: [src/mcp/storage/vectors.ts:28-33]() ## Known Limitations Several issues from the project's tracker directly affect this module and are worth noting before relying on it at scale: | Area | Limitation | Source | |------|------------|--------| | Ignore rules | Only the root `.gitignore` is honored; nested rules are ignored, so files git already excludes still get indexed | [file-discovery.ts:124-134]() (issue #57) | | Startup cost | All 13 tree-sitter WASM grammars load eagerly at startup, wasting ~30MB when only a few languages are present | [parser-pool.ts:206-289]() (issue #50) | | Discovery speed | Synchronous `fs.lstatSync` plus low parser concurrency makes large repos index 5–10× slower than necessary | [file-discovery.ts]() (issue #51) | | First-search latency | ONNX model lazy init can race with the first query | [vectors.ts:28-33]() (issue #52) | | Indexer queries | `LIKE '%term%'` over `coding_standards` forces a full table scan; FTS5 is not used | [entities/standard.ts:90-152]() (issue #53) | Together, these define the practical envelope of the module: it is correct and feature-complete for small-to-medium repositories, but performance-sensitive users should plan for eager-parser memory overhead and should pre-warm the vector store before serving traffic. --- ## Memory Management, Semantic Search, and Knowledge Graph ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Codebase Index and Source Code Search](#page-2), [Dashboard UI, Performance, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [src/mcp/entities/memory.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/memory.ts) - [src/mcp/entities/standard.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/standard.ts) - [src/mcp/entities/memory.vector.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/memory.vector.ts) - [src/mcp/entities/memory.archive.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/memory.archive.ts) - [src/mcp/entities/task.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/task.ts) - [src/mcp/entities/handoff.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/handoff.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/vectors.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/vectors.ts) - [src/mcp/storage/migrations.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/storage/migrations.ts)
# Memory Management, Semantic Search, and Knowledge Graph ## Purpose and Scope The Memory Management subsystem in `local-memory-mcp` provides persistent, structured storage for memories, tasks, coding standards, and handoffs scoped to a `(owner, repo)` pair. It supports both **keyword search** (SQLite `LIKE`-based) and **semantic vector search** (ONNX-based embeddings), and links records into a Knowledge Graph via explicit relations. Source: [src/mcp/entities/standard.ts:90-152](). The subsystem composes three layers: - **Entity layer** — domain tables (`memory`, `task`, `handoff`, `coding_standards`, `archive`) with CRUD, conflict detection, and recall tracking. - **Storage layer** — SQLite migrations defining composite-friendly columns, plus a pluggable vector store (`RealVectorStore` for ONNX, `StubVectorStore` for tests). - **Tool layer** — MCP-exposed tools (`memory-recall`, `memory-store`, `task-create`, `handoff-save`, etc.) routed through `tools/index.ts`. The Knowledge Graph is **derived**: nodes are memory/task/codebase entities and edges come from `RELATIONS` tables that store directional `from`/`to` links with optional weight. Source: [src/mcp/entities/memory.ts](). ## Entity Model and Persistence Each entity extends a shared `StandardEntity` base class providing lifecycle helpers. The `MemoryEntity` stores textual records with fields `title`, `content`, `context`, `tags`, and recall-hit counters. Source: [src/mcp/entities/memory.ts]()`. Archival is a first-class concern: instead of hard-deleting, records are moved to the `archive` table. `MemoryArchiveEntity` mirrors `MemoryEntity` schema, enabling undelete and history review. Source: [src/mcp/entities/memory.archive.ts](). Task and handoff models extend the same base: - `TaskEntity` tracks open/closed states, assignees, and references memory IDs (`memory_ids`) for traceability. Source: [src/mcp/entities/task.ts](). - `HandoffEntity` captures session-to-session continuity payloads with TTL fields. Source: [src/mcp/entities/handoff.ts](). Migrations live in `src/mcp/storage/migrations.ts` and provision column-level indexes on `repo`, but notably **lack composite `(owner, repo)` indexes** — a known performance gap that causes full-table scans on multi-tenant queries. Source: [src/mcp/storage/migrations.ts]() (see issue #49). ## Semantic Search and Vector Store Semantic recall uses a pluggable `VectorStore` interface. Two implementations ship: | Store | Embedding | Vector persistence | Use case | |-------|-----------|--------------------|----------| | `RealVectorStore` | `Xenova/all-MiniLM-L6-v2` ONNX model | True dense vectors | Production semantic recall | | `StubVectorStore` | Token-frequency, then zero-filled | Trivial vectors, recomputed on read | Tests, offline mode | The `RealVectorStore` lazy-loads the ONNX model on first `getExtractor()` call, which is started in `initialize()` without awaiting — introducing a startup race risk. Source: [src/mcp/storage/vectors.ts:28-33]() (issue #52). The `StubVectorStore.upsert()` tokenizes input text but stores `tokens.map(() => 0)` rather than real TF-IDF vectors; `search()` then re-tokenizes and re-computes frequency vectors from stored content. Source: [src/mcp/storage/vectors.stub.ts:62-135]() (issue #55). The `MemoryEntity` integrates the vector store via `searchBySimilarity()`, which delegates to the active implementation and returns ranked candidates with cosine scores. Source: [src/mcp/entities/memory.vector.ts](). ### Conflict Detection (`checkConflicts`) `StandardEntity.checkConflicts()` at lines 214-260 invokes `searchBySimilarity()`, then iterates the **same candidate set** a second time to re-apply a threshold filter, recomputing cosine similarity each pass. Source: [src/mcp/entities/standard.ts:214-260]() (issue #56). The duplicated loop is a documented optimization target — the candidates and scores should be reused. ## Search, Recall, and Knowledge Graph Recall flows through three MCP tools exposed by `tools/index.ts:83-116`: 1. `memory-recall` — combines `StandardEntity.search()` (text `LIKE`) with `MemoryEntity.searchBySimilarity()` (vector `cosine`). 2. `memory-store` — upserts and triggers vector indexing if enabled. 3. `memory-acknowledge` / `incrementHitCount` / `incrementRecallCount` — write tools that bump counters under an inter-process `proper-lockfile` lock. Source: [src/mcp/tools/index.ts:83-116]() (issue #47). A SQL snippet from `StandardEntity.search()` illustrates the keyword path: ```sql WHERE (title LIKE '%term%' OR content LIKE '%term%' OR context LIKE '%term%') ``` Leading-wildcard `LIKE` cannot use indexes, forcing full-table scans — issue #53 tracks the FTS5 migration plan. Source: [src/mcp/entities/standard.ts:90-152](). ### Data Flow ```mermaid flowchart LR Tool[mcp tool] --> Router[router normalizeToolArguments] Router --> Entity[StandardEntity.search] Entity --> SQL[(SQLite memories)] Entity --> VS[VectorStore.searchBySimilarity] VS --> OR[(memory_vectors table)] SQL --> Result[ranked results] OR --> Result Result --> KG[Knowledge Graph relations] ``` The Knowledge Graph visualization (plan in issue #58) will unify memory, codebase-symbol, and task nodes into a single force-directed view, replacing the current KG-tab that shows only entities/relations. Source: [issue #58](). ## Known Limitations Summary - **Indexing**: Missing composite `(owner, repo)` indexes cause full-table scans (issue #49). - **Search**: `LIKE '%term%'` not FTS5-accelerated (issue #53). - **Vectors**: ONNX lazy-init can race the first request (issue #52); `StubVectorStore` recomputes vectors on every search (issue #55). - **Conflicts**: `checkConflicts` performs cosine similarity twice over the same candidate set (issue #56). - **Locking**: Write tools contend on `proper-lockfile` (50s max wait) — read/write tool classification should be revisited (issue #47). - **Knowledge Graph**: Currently entity-only; unified neural-network graph planned (issue #58). --- ## Dashboard UI, Performance, and Operations ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Codebase Index and Source Code Search](#page-2), [Memory Management, Semantic Search, and Knowledge Graph](#page-3)
Related Source Files The following source files were used to generate this page: - [src/dashboard/server.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/server.ts) - [src/dashboard/controllers/SystemController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/SystemController.ts) - [src/dashboard/controllers/MemoriesController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/MemoriesController.ts) - [src/dashboard/controllers/TasksController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/TasksController.ts) - [src/dashboard/controllers/KGController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/KGController.ts) - [src/dashboard/controllers/UnifiedGraphController.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/dashboard/controllers/UnifiedGraphController.ts) - [src/mcp/tools/index.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/tools/index.ts) - [src/mcp/router.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/router.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) - [src/mcp/entities/standard.ts](https://github.com/vheins/local-memory-mcp/blob/main/src/mcp/entities/standard.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) - [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)
# Dashboard UI, Performance, and Operations The dashboard is the operational front-end of `local-memory-mcp`, exposing a controller-based HTTP surface mounted by `src/dashboard/server.ts`. It serves read/write views over memories, tasks, the knowledge graph (KG), and (planned) a unified neural-style graph. It shares the same SQLite backend and process-locking semantics as the MCP tool layer, which means many performance characteristics of the dashboard are inherited from the storage and indexing subsystems it queries. ## Dashboard Architecture The dashboard follows a thin Express-style controller pattern. Each controller maps a slice of functionality to HTTP handlers and delegates data access to the shared `db` instance: - `SystemController` provides repository-scoped operations including a global export endpoint that aggregates memories, tasks, comments, and KG data. Source: [src/dashboard/controllers/SystemController.ts:142-177]() - `MemoriesController` exposes CRUD and search over the `memories` table, including recall-rate enriched queries. - `TasksController` manages `tasks` and `taskComments` for the kanban-style task view. - `KGController` returns entities/relations for the current Knowledge Graph tab. - `UnifiedGraphController` is the planned entry point for the unified force-directed visualization (issue #58) that combines memories, codebase symbols, and tasks as one interconnected node set. All controllers are wired into the dashboard server in `src/dashboard/server.ts`, which also owns static asset serving and session-level owner/repo resolution. ## Known Performance Bottlenecks The community has filed a tightly clustered set of performance issues (v0.23.0) that together describe the operational hot spots of the system. They group into four themes. ### 1. Dashboard query and export path `SystemController.getExport()` materializes the entire repo in memory before serializing: - `db.memories.getAllMemoriesWithStats("", repo)` with a per-row `recall_rate` subquery. - `db.tasks.getTasksByRepo("", repo)` and `db.taskComments.getAllTaskComments(...)`. - These run unbounded, producing OOM risk on large repositories. Source: [src/dashboard/controllers/SystemController.ts:142-177]() ### 2. Indexing pipeline latency The codebase indexer has two independent slow paths: - `fs.lstatSync` in `file-discovery.ts:124-134` blocks the event loop and prevents parallelism; combined with low concurrency it makes large-repo indexing 5–10× slower than necessary. Source: [src/mcp/codebase-index/services/file-discovery.ts:124-134]() - `TreeSitterParserPool._doInitialize()` at `parser-pool.ts:206-289` eagerly loads all 13 language grammar WASM binaries (C, C++, Dart, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift, TypeScript) via `Promise.allSettled()`, wasting 30MB+ on cold start for users who only touch one language. Source: [src/mcp/codebase-index/parser/parser-pool.ts:206-289]() ### 3. Storage and vector path Three storage-layer issues compound in the dashboard's search and suggestion endpoints: - `RealVectorStore` at `src/mcp/storage/vectors.ts:28-33` lazily loads the `Xenova/all-MiniLM-L6-v2` ONNX model on first call, but `initialize()` does not await it — the first dashboard similarity request may stall until extraction completes. Source: [src/mcp/storage/vectors.ts:28-33]() - `StubVectorStore.upsert()` at `src/mcp/storage/vectors.stub.ts:62-81` stores `tokens.map(() => 0)` instead of the real TF-IDF vector, forcing `search()` to re-tokenize and recompute the full vector on every query. Source: [src/mcp/storage/vectors.stub.ts:62-135]() - `StandardEntity.search()` uses `LIKE '%term%'` over title/content/context, which cannot use SQLite indexes and forces full table scans; replacing this with FTS5 is the proposed fix. Source: [src/mcp/entities/standard.ts:90-152]() - The same entity's `checkConflicts()` recomputes cosine similarity twice on the same candidate set. Source: [src/mcp/entities/standard.ts:214-260]() ### 4. Locking and schema overhead - `memory-acknowledge`, `incrementHitCount`, and `incrementRecallCount` are classified as write tools in `WRITE_TOOLS` (issue #47), so each call takes an inter-process `proper-lockfile` lock with 250 retries at 200ms (≈50s worst case). Source: [src/mcp/tools/index.ts:83-116]() - Migrations create single-column indexes on `repo` but most queries filter by both `owner` and `repo`, so SQLite picks only one index and scans the rest. Source: [src/mcp/storage/migrations.ts]() ## Cross-Cutting Refactors Two non-performance issues affect dashboard reliability and maintainability: - `normalizeToolArguments` (~80 lines) is duplicated between `src/mcp/router.ts:387-473` and `src/mcp/tools/index.ts:133-242`, with near-identical owner/repo injection, scope parsing, and root-bound path validation. The dashboard benefits indirectly because both paths must be kept in sync for safe owner scoping. Source: [src/mcp/router.ts:387-473]() - `file-discovery.ts:124-134` ignores nested `.gitignore` files common in monorepos (`packages/foo/.gitignore`), causing git-ignored files to be indexed and surfaced in dashboard views. Source: [src/mcp/codebase-index/services/file-discovery.ts:124-134]() ## Operational Implications The accumulated weight of these issues means the dashboard's performance ceiling is not set by its HTTP layer but by the storage and indexing subsystems underneath it. The most impactful operational mitigations, in priority order, are: | Area | Bottleneck | Recommended Action | |------|------------|--------------------| | Dashboard export | Unbounded `getAll*` queries | Stream/serialize in pages | | Tool writes | Lock contention on ack/hit tools | Reclassify as read or use per-row locks | | Search | `LIKE '%term%'` full scan | Migrate to FTS5 virtual table | | Indexing | Sync `lstatSync` + eager WASM | Async `fs.promises.lstat`, lazy grammar loading | | Schema | Single-column indexes | Add composite `(owner, repo)` indexes | The unified neural network graph (issue #58) will multiply these concerns by joining three large node sets, so resolving the indexing and export bottlenecks is a prerequisite before enabling that view in production. Source: [src/dashboard/controllers/UnifiedGraphController.ts]() --- --- ## Pitfall Log Project: vheins/local-memory-mcp Summary: Found 37 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: feat: full-local natural language codebase search (codebase_search tool) - User impact: Developers may fail before the first successful local run: feat: full-local natural language codebase search (codebase_search tool) - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/45 ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: feat: tambahkan monorepo workspace seperti turbo repo - User impact: Developers may fail before the first successful local run: feat: tambahkan monorepo workspace seperti turbo repo - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/42 ## 3. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste - User impact: Developers may fail before the first successful local run: perf: tree-sitter grammar WASMs eager-loaded at startup — 30MB+ waste - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/50 ## 4. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/45 ## 5. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/57 ## 6. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/51 ## 7. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/50 ## 8. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/vheins/local-memory-mcp ## 9. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: feat: unified neural network graph for memory, codebase, and task visualization - User impact: Developers may misconfigure credentials, environment, or host setup: feat: unified neural network graph for memory, codebase, and task visualization - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/58 ## 10. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: perf: missing composite indexes on (owner, repo) — full table scans on frequent queries - User impact: Developers may misconfigure credentials, environment, or host setup: perf: missing composite indexes on (owner, repo) — full table scans on frequent queries - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/49 ## 11. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v0.20.4 — Multi-language Parsing - User impact: Upgrade or migration may change expected behavior: v0.20.4 — Multi-language Parsing - Evidence: failure_mode_cluster:github_release | https://github.com/vheins/local-memory-mcp/releases/tag/v0.20.4 ## 12. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/48 ## 13. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/49 ## 14. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/vheins/local-memory-mcp ## 15. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/56 ## 16. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/52 ## 17. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/46 ## 18. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/54 ## 19. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/vheins/local-memory-mcp ## 20. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: 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 - User impact: Developers may hit a documented source-backed failure mode: perf: coding_standards uses LIKE %term% without FTS5 — full table scan on every search - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/53 ## 21. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: v0.21.0 — Codebase Search NL + FTS5 Standards - User impact: Upgrade or migration may change expected behavior: v0.21.0 — Codebase Search NL + FTS5 Standards - Evidence: failure_mode_cluster:github_release | https://github.com/vheins/local-memory-mcp/releases/tag/v0.21.0 ## 22. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/vheins/local-memory-mcp ## 23. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/vheins/local-memory-mcp ## 24. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/vheins/local-memory-mcp ## 25. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/58 ## 26. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/55 ## 27. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/vheins/local-memory-mcp/issues/53 ## 28. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: fix: double vector computation in StandardEntity.checkConflicts - User impact: Developers may hit a documented source-backed failure mode: fix: double vector computation in StandardEntity.checkConflicts - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/56 ## 29. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: fix: nested .gitignore not respected during file discovery - User impact: Developers may hit a documented source-backed failure mode: fix: nested .gitignore not respected during file discovery - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/57 ## 30. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk - User impact: Developers may hit a documented source-backed failure mode: perf: RealVectorStore ONNX model blocks first request — lazy init timeout risk - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/52 ## 31. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search - User impact: Developers may hit a documented source-backed failure mode: perf: StubVectorStore upsert stores zero-filled vectors — redundant computation on search - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/55 ## 32. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: perf: dashboard export loads entire DB into memory — OOM risk - User impact: Developers may hit a documented source-backed failure mode: perf: dashboard export loads entire DB into memory — OOM risk - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/48 ## 33. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline - User impact: Developers may hit a documented source-backed failure mode: perf: synchronous lstatSync + low concurrency bottlenecks in indexing pipeline - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/51 ## 34. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: perf: write lock contention on memory-acknowledge and hit-count tools - User impact: Developers may hit a documented source-backed failure mode: perf: write lock contention on memory-acknowledge and hit-count tools - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/47 ## 35. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts - User impact: Developers may hit a documented source-backed failure mode: refactor: normalizeToolArguments duplicated between router.ts and tools/index.ts - Evidence: failure_mode_cluster:github_issue | https://github.com/vheins/local-memory-mcp/issues/54 ## 36. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/vheins/local-memory-mcp ## 37. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/vheins/local-memory-mcp