1. 项目定位

NeuralMind 是一个面向代码库的语义检索与知识压缩系统，旨在通过对源代码建立可查询的"知识图谱"，让开发者和 LLM 代理能够跨越多个文件、模块与包边界，快速定位与当前任务相关的上下文。系统本身既是工具，也是一套自评估框架——它内置了 hermetic（自包含、可复现）的基准测试夹具，用于客观衡量自身相对其他代码库记忆方案的检索质量。

根据公开的发布历史，NeuralMind 的迭代呈现出两条主线：

• 多语言代码抽取：通过统一的 tree-sitter seam 接入新的语言解析器，使更多语言的代码能够被索引；
• 学习信号的统一：将原本分散的 learned_patterns 重排序器退役，把检索质量的提升统一收敛到 synapse 层这一单一学习信号。

2. 系统架构概览

NeuralMind 的整体架构可以分为四层：语言抽取层、图谱构建层、检索与学习层、以及对外接口层。下图展示了高层的数据流：

flowchart LR
    A[源代码仓库] --> B[tree-sitter 抽取层]
    B --> C[图谱构建层]
    C --> D[向量索引]
    C --> E[关系图谱]
    D --> F[检索与 synapse 学习层]
    E --> F
    F --> G[CLI / HTTP / MCP 接口]
    G --> H[LLM 代理 / 开发者]

2.1 语言抽取层（tree-sitter seam）

系统使用 tree-sitter 作为统一的语法解析后端，并已通过独立发布逐步接入多种主流语言。从发布历史可以确认该 seam 已覆盖的语言包括：Python、JavaScript/TypeScript、Java、Rust、C、C++，以及在最新版本中新增的 C#。这种"八种语言共用同一抽取接口"的设计，使得新增语言时只需实现对应的语法映射，无需触动上层图谱与检索逻辑。

2.2 图谱构建层与基准夹具

NeuralMind 提供了一个名为 sample_project 的演示项目作为基准测试夹具。该夹具刻意设计为"足够大以具备跨文件关联、足够小以保证 CI 运行快速、完全静态无需运行时依赖"：

• auth/ 处理登录与 JWT 验证；
• billing/ 封装 Stripe 充值与发票逻辑；
• users/ 提供用户模型与 CRUD；
• api/ 负责 HTTP 路由的粘合层；
• db/ 提供连接池。

夹具中的 api/routes.py 文件展示了典型的端到端调用链——例如 charge_endpoint 会先通过 verify_session 校验 Bearer token，再调用 billing 模块的 charge_customer，从而在图谱中形成清晰的多文件调用关系。这种刻意构造的耦合关系，使基准测试能够稳定地衡量"跨文件语义检索"这一核心能力。

2.3 检索与 Synapse 学习层

自 v0.25.0 起，系统将唯一的检索质量学习信号收敛到 synapse 层，替代了旧的 learned_patterns 重排序器；v0.26.0 引入了基于 synapse 反馈的 self-improvement engine 阶段 1-2，用于对选择器（selector）进行自动调优。这一设计意味着：所有与"如何挑出最相关上下文"相关的策略，都从同一处反馈信号中学习，避免了多套学习机制互相冲突。

2.4 对外接口与基准对比

NeuralMind 通过 CLI、benchmark --public 命令，以及在 v0.33.0 起加入的 codebase-memory-mcp 实时对比，向用户和 LLM 代理暴露能力。其中：

• neuralmind build <path> --force：重建指定代码库的索引（夹具 README 中即采用此流程）；
• neuralmind benchmark --public：执行对外可复现的基准，与其他代码库记忆方案进行 head-to-head 对比；
• v0.34.0 增加了可选的 LLM-judged 可回答性评测臂，以更准确地评估检索结果对真实问答场景的支撑能力。

3. 关键设计取舍

4. 常见使用模式

对于希望快速体验或贡献的开发者，推荐流程如下：

1. 在本地修改 demo_data/sample_project/ 下的任一文件；
2. 运行夹具 README 中描述的 graphify update . 与 neuralmind build ... --force 命令，重新生成索引；
3. 运行 neuralmind benchmark --public 观察检索质量变化。

CI 环境会自动完成上述流程的等价步骤，因此本地重生成主要用于加速迭代。

5. 已知与演进中的方向

从近期发布来看，团队正在持续扩展语言覆盖（C# 是第八种语言）、扩充公共基准语料（新增 flask、rich 等项目），并以 LLM-judged 的可回答性作为新的评估维度。这些工作共同指向一个目标：让 NeuralMind 既能在多语言真实仓库中保持高质量检索，又能以可证伪的方式证明这一点。

See Also

• 示例夹具说明
• 示例 HTTP 路由

资料来源：

• demo_data/sample_project/README.md:1-30
• demo_data/sample_project/api/routes.py:1-40

概述与设计目标

NeuralMind 的核心能力之一是把任意主流语言的源代码转成可被语义检索使用的"代码知识图谱"。为了让"加一种语言"不再意味着改一整套下游管线,系统采用 Tree-sitter 作为统一语法骨架:Tree-sitter 为每种语言提供增量式、错误容忍的 AST,NeuralMind 只需要在 AST 之上挂接一个轻量的"语言提取器"即可产出统一的中间表示(IR)。v0.37.0 公告将 C# 称为"第八种接入 tree-sitter 接入缝(seam)之后的语言",这说明该 seam 是所有新增语言的唯一接入边界,所有下游组件(图谱、检索、自改进引擎)都只与 IR 打交道,与源语言无关。

语言支持历程

下表汇总了公开的发布记录中、明确以"加入 Tree-sitter 后端"为标题的语言扩展事件:

Python 在更早的版本中已是默认 fixture(见下文 sample_project),因而 v0.37.0 公告把它称为"第八种语言"时,意味着前七种中至少包含 Python 与 v0.27 / v0.28 / v0.32 中所列的若干种。资料来源:Release v0.37.0、Release v0.27.0。

后端数据流

flowchart LR
    SF[源代码文件] --> TS[Tree-sitter 解析器]
    TS --> LR{语言路由器}
    LR --> PY[Python 提取器]
    LR --> RS[Rust 提取器]
    LR --> JV[Java 提取器]
    LR --> CC[C / C++ 提取器]
    LR --> CS[C# 提取器]
    PY --> IR[统一中间表示]
    RS --> IR
    JV --> IR
    CC --> IR
    CS --> IR
    IR --> KG[代码知识图谱]
    KG --> RET[语义检索 / 自改进]

所有语言提取器将各自的 AST 节点折叠为 IR 节点;IR 既是图谱构建的输入,也是 self-improvement 引擎(见 v0.26.0 的"synapse signal")和公共基准(见 v0.31.0 的 neuralmind benchmark --public)读取的唯一契约。资料来源:Release v0.26.0、Release v0.31.0。

端到端构建示例

仓库自带的 demo_data/sample_project 是一个约 500 行、跨 ~10 个 Python 文件的"微型 web 应用",其设计目的正是验证多文件依赖场景下的解析与图谱构建。README 明确指出它"足够大以具有跨文件关系(auth 依赖 users + JWT,billing 依赖 users,api 把所有部分连起来)",且无运行时依赖,可在 CI 中作为固定装置快速复现。资料来源:neuralmind/demo_data/sample_project/README.md:1-12。

以 api/routes.py 为例,文件顶部以相对导入 from ..auth.handlers import ...、from ..billing.stripe_client import ...、from ..users.crud import ... 拉入同级子包,这些路径在被 Tree-sitter 抽取后,会变成图谱里的"模块依赖边"。其本地重建流程如下:

# 1. 重建知识图谱依赖
pip install graphifyy
cd tests/fixtures/sample_project
graphify update .

# 2. 强制重建 NeuralMind 索引
cd ../../..
neuralmind build tests/fixtures/sample_project --force

CI 会自动执行该流程,本地重复构建仅在需要快速迭代时才有意义。资料来源:neuralmind/demo_data/sample_project/README.md:25-35。

常见使用模式与配套配置

1. 新增一种语言 只需在 tree-sitter seam 之后追加一个语言提取器,IR 与检索层不必修改——v0.27 / v0.28 / v0.32 / v0.37 的连续发布验证了这一模式的可重复性。
2. 轻量默认安装 与语言扩展正交:从 v0.29.0 起,默认安装不再捆绑 ChromaDB,改用 turbovec/ONNX 嵌入后端,新增语言时不会额外加重依赖。资料来源:Release v0.29.0。
3. 基准与回归 通过 v0.31.0 引入的 neuralmind benchmark --public 与 sample_project 之类的固定装置,可在每次语言扩展后自动比对召回率与图谱质量。

See Also

• 公共基准测试套件(参见 v0.31.0 的 neuralmind benchmark --public)
• LLM-judged answerability 评估臂(参见 v0.34.0)
• 自改进引擎与 synapse 信号(参见 v0.26.0)
• 轻量默认安装(参见 v0.29.0)

概述

NeuralMind 的检索质量与自适应能力由三个相互耦合的子系统支撑：突触记忆层（Synapse Memory Layer）作为重排序与学习的唯一信号源；命名空间（Namespaces）为索引、向量、突触与团队记忆提供隔离边界；自学习引擎（Self-Improvement Engine）则消费突触信号持续微调检索路径上的选择器（selector）参数。三者通过 neuralmind/memory.py 中的通用记忆层桥接，形成"检索 → 反馈 → 调优"的闭环。

突触记忆层

自 v0.25.0 起，原有的 learned_patterns 重排序器被正式弃用，突触层成为系统唯一的学习信号通道 (release v0.25.0)。其结构与职责分布在两个文件：

• neuralmind/synapses.py 定义突触对象、激活规则与衰减策略；
• neuralmind/synapse_memory.py 负责突触的持久化、跨进程共享与命名空间内分片。

突触层与 neuralmind/memory.py 暴露的通用记忆读写接口共用底层存储，因此重启进程后学习信号不会丢失。

命名空间

命名空间是 NeuralMind 多项目/多租户隔离的基础抽象，由 neuralmind/namespaces.py 实现。它为以下资源提供独立键空间：

v0.31.0 引入 neuralmind/team_memory.py，允许在同一命名空间内不同成员间共享长期记忆条目 (release v0.31.0)，但跨命名空间的条目不会相互可见。

自学习引擎

neuralmind/self_improve.py 实现了自学习引擎。v0.26.0 公开了阶段 1-2 的功能：选择器（selector）自动调优，直接消费突触层信号作为监督 (release v0.26.0)。其核心循环为：

1. 检索器产出候选 → 突触层记录命中与用户反馈；
2. 自学习引擎以突触信号为唯一监督，更新选择器权重；
3. 下一次检索时使用更新后的选择器，闭环回到步骤 1。

flowchart LR
    Q[Query] --> R[Retriever]
    R --> S["Synapse Memory Layer<br/>(neuralmind/synapses.py)"]
    S --> RR[Re-rank]
    RR --> Resp[Response]
    Resp -.feedback.-> SI["Self-Improvement Engine<br/>(neuralmind/self_improve.py)"]
    SI -.tune.-> S
    NS["Namespaces<br/>(neuralmind/namespaces.py)"] -.isolate.-> S
    NS -.isolate.-> SI

常见失败模式

• 冷启动：突触层尚未累积足够反馈时，自学习引擎几乎不更新选择器，初次部署的检索质量与基线无异；
• 命名空间串扰：跨项目共享底层存储路径时，突触信号可能被错误聚合，建议显式使用 namespaces.py 提供的键派生接口；
• 遗留权重：v0.25.0 之前构建的 learned_patterns 旧权重若未清理，可能与突触信号产生冲突，应在升级时移除。

See Also

• 公共基准与可复现性（v0.31.0）
• ChromaDB-free 默认安装（v0.29.0）
• tree-sitter 多语言后端：Rust (v0.27.0)、Java (v0.28.0)、C/C++ (v0.32.0)、C# (v0.37.0)

概述

NeuralMind 在 v0.31.0 之后逐步建立起由"公开基准（neuralmind benchmark --public）"、"可插拔嵌入后端（embedding backend）"与"对外 MCP（Model Context Protocol）代理"三部分组成的能力栈。本页围绕这三者说明其目的、默认行为与相互协作方式，所有论断均基于本仓库源码与公开发布日志可证的内容。

公开基准（`neuralmind benchmark --public`）

公开基准的入口在 v0.31.0 中以 neuralmind benchmark --public 形式引入，定位是"诚实、可复现"的对外评测命令 资料来源：release v0.31.0。该基准运行在仓库自带的 demo_data/sample_project 之上：约 10 个文件、约 500 行代码、跨 auth/、billing/、users/、api/、db/ 的真实依赖关系，足够触发跨文件语义检索，又足够小以保证 CI 单次运行足够快 资料来源：neuralmind/demo_data/sample_project/README.md:1-15。

此后基准能力按版本扩展：

• v0.33.0：在公开基准中纳入 codebase-memory-mcp 的同场对比（head-to-head）资料来源：release v0.33.0。
• v0.34.0：新增 opt-in 的 LLM-judged answerability 评估臂，由用户自行决定是否启用 资料来源：release v0.34.0。
• v0.37.0：扩展公开基准语料库，新增 flask、rich 等项目 资料来源：release v0.37.0。

由于夹具是纯静态的 Python Web 应用样板代码，CI 可在无外部运行时依赖的情况下直接复现 资料来源：neuralmind/demo_data/sample_project/README.md:5-12。

嵌入后端（Embedding Backend）

NeuralMind 通过 embedding_backend 抽象统一所有向量检索实现，资料来源：neuralmind/embedding_backend.py。后端调度由 backend_manager.py 完成，可用的具体实现至少包括：

v0.29.0 起，默认安装改为 ChromaDB-free：默认后端切换为 turbovec / ONNX 组合，显著降低了外部服务依赖与冷启动时间 资料来源：release v0.29.0。embedder.py 负责在 build 阶段把代码片段编码为向量并写入所选后端 资料来源：neuralmind/embedder.py。

MCP 代理集成（Model Context Protocol）

MCP 集成使 NeuralMind 知识图谱可作为外部代理（agent）的工具/上下文提供者。从 v0.33.0 起，codebase-memory-mcp 被直接纳入公开基准的对比臂，验证 NeuralMind 在多文件关系重建、跨模块语义检索方面的相对表现 资料来源：release v0.33.0。

样例夹具中，api/routes.py 通过 route() 装饰器把 auth/handlers、billing/stripe_client、billing/invoices、users/crud 等模块的方法聚合到统一路由表 资料来源：neuralmind/demo_data/sample_project/api/routes.py:9-79。这种"装饰器注册 → 跨模块调用"的模式正是 MCP 代理在做"在某路由背后，到底是哪些模块协同完成请求"这类查询时必须能解析的依赖关系；auth 依赖 users 与 JWT、billing 依赖 users 等关系共同构成了代理可消费的"代码语义上下文" 资料来源：neuralmind/demo_data/sample_project/README.md:13-20。

配置、协作流程与常见失败模式

三者协作的典型数据流如下：

flowchart LR
    A[sample_project 源码] --> B[neuralmind build]
    B --> C{backend_manager}
    C --> D[turbovec_backend]
    C --> E[onnx_embedder]
    C --> F[in_memory_backend]
    D --> G[(向量存储)]
    E --> G
    F --> G
    G --> H[MCP 代理查询]
    H --> I[neuralmind benchmark --public]

常见失败模式与处理建议：

• 后端与索引不匹配：切换 backend_manager 所选后端后，未执行 neuralmind build --force，旧向量与新维度可能不一致。修改 sample_project 内的源文件后，应按 README 中的步骤先重建图谱再重新 build 资料来源：neuralmind/demo_data/sample_project/README.md:23-31。
• 基准结果不可复现：未使用 --public 而直接调用本地索引，会丢失 hermetic 夹具 资料来源：release v0.31.0。
• LLM-judged 评估臂报错：v0.34.0 引入的该臂为 opt-in，需自行配置 LLM 凭据，否则应保持关闭 资料来源：release v0.34.0。

See Also

• 自改进引擎 phases 1-2：基于突触信号的选择器自动调优（v0.26.0）
• 突触层作为单一学习信号，退役 learned_patterns 重排器（v0.25.0）
• tree-sitter 多语言后端：Rust/Java/C、C++/C# 扩展（v0.27.0–v0.37.0）

Pitfall Log / 踩坑日志

项目：dfrostar/neuralmind

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

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

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

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

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

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

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

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