项目定位与设计目标

NeuroStack 是一个本地优先（local-first）、AI 提供方无关的知识管理与检索工具，当前版本为 0.10.1。资料来源：src/neurostack/__init__.py:1-9 中将其明确定义为 "AI-provider-agnostic, neuroscience-grounded knowledge management"。项目的核心目标是让用户在本地构建一个可被智能检索、相互链接的第二大脑，并通过统一协议与外部 LLM 协作,而非将数据上传到云端。

依据资料来源：README.md:1-40，项目跨平台支持 Windows / Linux / macOS，最低仅需 4 GB 内存与约 100 MB 磁盘空间；AI 功能是可选增强项而非必备依赖。资料来源：npm/README.md:1-15 进一步说明其同时提供 Python 与 npm 两套分发形态。

系统架构总览

NeuroStack 采用 "工具定义 + 协议适配" 的分层架构。业务功能以 Python 函数形式通过统一注册中心暴露，再由若干 Adapter 分别翻译为 REST、OpenAI Function Calling、MCP 等不同协议，从而被命令行、HTTP 客户端或 AI Agent 进程调用。

flowchart TB
    subgraph 协议适配层[Protocol Adapters]
        REST["REST Adapter<br/>POST /v1/tools/{name}<br/>GET /v1/tools"]
        OAI["OpenAI Adapter<br/>function calling schema"]
        MCP["MCP Adapter<br/>FastMCP / stdio"]
    end

    REG["ToolRegistry<br/>@registry.tool 装饰器"]

    subgraph 业务工具集[Business Tools]
        SRCH["search_tools<br/>vault_search / vault_ask"]
        MEM["memory_tools<br/>vault_memories / vault_capture"]
        INS["insight_tools<br/>session_brief / vault_context"]
    end

    subgraph 存储与同步[Storage & Sync]
        DB[("SQLite + FTS5")]
        VAULT["Markdown Vault"]
        CLOUD["Content-Hash Manifest<br/>SHA-256"]
    end

    AI["LLM / Embedding<br/>OpenAI-compatible endpoint"]

    REST --> REG
    OAI --> REG
    MCP --> REG
    REG --> SRCH
    REG --> MEM
    REG --> INS
    SRCH --> DB
    SRCH --> VAULT
    SRCH --> AI
    MEM --> DB
    INS --> DB
    VAULT <--> CLOUD

核心模块剖析

工具注册与协议适配层

所有功能均通过单例 ToolRegistry 注册。资料来源：src/neurostack/tools/registry.py:50-90 指出，开发者使用 @registry.tool(tags=[...]) 装饰器即可声明一个工具；参数 schema 通过 inspect.signature 自动抽取，docstring 首段被 _extract_description 抽取为描述。注册后的工具再由三类 Adapter 暴露：

OpenAI Adapter 额外截断 docstring 至 1024 字符以满足 OpenAI 描述字段上限；REST Adapter 通过 _param_to_json_schema 将 Python 类型转换为 JSON Schema；MCP Adapter 则用 functools.wraps 保留签名与文档，避免协议层签名漂移。

检索与上下文装配层

检索层采用"分层深度（depth）"策略以权衡 token 成本。资料来源：src/neurostack/skills/vault-search.md:1-25 列出了 triples / summaries / full / auto 四种 depth 取值，分别对应 SPO 三元组、预生成摘要、全文片段与系统自动决策。vault_ask 在此基础上封装为标准 RAG 流程：调用 hybrid_search → 拼接 prompt → 经 httpx 调用 OpenAI 兼容端点（temperature=0.3、max_tokens=500） → 剥离 <think> 标签 → 返回带 [[note-title]] 内联引用的答案。资料来源：src/neurostack/ask.py:50-100。

上下文工具则面向"会话恢复"场景：session_brief 提供约 500 token 的时间锚定快照（最近变更、git commits、记忆、连接最密的笔记）；vault_context 按任务描述在默认 2000 token 预算内拉取记忆、三元组、摘要与历史。资料来源：src/neurostack/tools/insight_tools.py:30-70。

存储、记忆与同步层

底层采用 SQLite + FTS5 提供全文检索能力。memory_tools 提供 vault_capture（零摩擦快速捕获到 inbox/）、vault_memories（FTS5 + 语义相似度混合检索）等能力，记忆类型涵盖 observation / decision / convention / learning / context / bug 六类。资料来源：src/neurostack/tools/memory_tools.py:60-100。

云同步通过 Manifest 扫描 vault 目录并计算 SHA-256 哈希，仅上传"新增"或"变更"文件。资料来源：src/neurostack/cloud/manifest.py:15-45 中 SyncDiff.has_changes 与 upload_files 属性明确界定了这一增量同步语义，避免重复传输。

健康审计能力由独立 skill 提供。资料来源：src/neurostack/skills/vault-audit.md:1-25 暴露了 vault_stats / vault_prediction_errors / vault_record_usage 等检查点，用于追踪嵌入覆盖率、检索质量与使用热度（hotness scoring）。

运行模式与部署形态

项目同时支持 full mode 与 lite mode 两种安装形态。资料来源：npm/README.md:20-35 与 npm/package.json:1-25 显示 npm 包通过 postinstall 脚本自动安装 uv、克隆仓库并创建虚拟环境；设置 NEUROSTACK_MODE=lite 即可跳过 ML 依赖获得最小化安装。Full mode 默认依赖 Ollama 上的 nomic-embed-text 与 qwen2.5:3b 模型。

REST API 入口由 create_app() 构建并在 run_server() 中通过 uvicorn 启动，监听来自配置的 api_host / api_port。资料来源：src/neurostack/api.py:80-110。该服务同时提供 OpenAI 兼容的 /v1/embeddings 端点，使 NeuroStack 可作为向量后端被其它应用复用。

See Also

• 工具注册中心与协议适配器详解
• 检索策略（triples / summaries / full）与 RAG 流程
• 记忆系统与内容哈希增量同步
• 安装模式（full / lite）与 CLI / npm 部署

架构概览

Tool Registry and Retrieval Engine 是 neurostack 的中枢模块，职责是把本地知识库（Markdown vault + SQLite + Embedding）的能力以"协议无关"的工具形式暴露给上层调用方（CLI、LLM、MCP/REST 客户端）。设计上坚持三点：

1. 单一注册中心：所有工具以 Python 函数 + @registry.tool(...) 装饰器登记到同一份 ToolRegistry 单例。
2. 多协议适配：同一份注册表被不同 adapter 渲染为 OpenAI function-calling、FastAPI REST、CLI/MCP 调用三种形态，调用方共享同一个工具名空间。
3. 按深度分级 + 按工作区隔离：检索工具以 depth ∈ {"triples","summaries","full","auto"} 控制成本，以 workspace 子目录前缀限定作用域。

整体调用链是 tool 函数 → ToolDef → registry → adapter → 客户端 → registry.call(...) → tool 函数 → dict 结果 → JSON。

注册表与适配器

ToolRegistry 是轻量内存字典，键为工具名，值为 ToolDef。装饰器 @registry.tool(name=..., tags=[...]) 接收可选 name 与 tags（如 ["search", "retrieval"]），并通过 inspect.signature 自动抽取参数类型生成 ToolParam 列表 资料来源：[src/neurostack/tools/registry.py:60-110](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/registry.py)。被装饰函数必须返回 dict，序列化交给上层处理；首次访问时由 ensure_registered() 惰性导入 insight_tools / memory_tools / search_tools / session_tools 四组工具完成填充 资料来源：[src/neurostack/tools/__init__.py:18-33](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/__init__.py)。

当前已落地的两条适配路径：

• OpenAI 适配器 把工具渲染为标准 {"type":"function","function":{...}} schema，并将模型返回的 name + arguments 反序列化后调用 registry.call(name, **arguments)，结果以 JSON 字符串回填到 tool_call.response 资料来源：[src/neurostack/tools/openai_adapter.py:30-90](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/openai_adapter.py)。
• REST 适配器 通过 create_tools_router(prefix="/v1/tools") 创建 FastAPI APIRouter，暴露 GET /v1/tools（列出全部工具的 JSON Schema）与 POST /v1/tools/{tool_name}（按名调用，参数取自 JSON body），把每个 ToolParam 自动转为 JSON Schema 资料来源：[src/neurostack/tools/rest_adapter.py:25-110](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/rest_adapter.py)。

这种"单注册中心 + 多适配器"模式让新增协议（例如 MCP）只需新增一个 adapter，注册表本体无需改动。

检索工具与分级深度

search_tools.py 是检索核心入口，提供 vault_search / vault_triples / vault_ask / vault_summary / vault_communities / vault_stats 等 资料来源：[src/neurostack/tools/search_tools.py:35-200](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/search_tools.py)。下表按用途与成本对比常用工具：

tiered_search 与 hybrid_search 在底层按 triples → summaries → full 自动降级，mode 支持 hybrid / semantic / keyword 三种召回方式。vault_ask 走标准 RAG：先用 hybrid_search 召回 top_k 片段，再用 OpenAI 兼容 chat-completion 端点作答，prompt 强制要求输出 [[note-title]] 内联引用 资料来源：[src/neurostack/ask.py:30-90](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/ask.py)。

上下文、会话与审计

除检索外，insight_tools.py 与 session_tools.py 提供"上下文/会话/审计"能力：

• session_brief(workspace=None)：约 500 token 的会话快照，包含最近 vault 变更、git commit、近期记忆、连接度最高的笔记及时间上下文，典型用途是新会话开场 资料来源：[src/neurostack/tools/insight_tools.py:30-60](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/insight_tools.py)。
• vault_context(task, token_budget=2000, include_memories=True, include_triples=True)：以"任务"为锚（而非时间），在 token 预算内召回相关记忆、三元组、摘要与会话历史，用途是 /clear 或切换会话后快速恢复 资料来源：[src/neurostack/tools/insight_tools.py:60-110](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/tools/insight_tools.py)。
• vault_stats()：直接查 SQLite 输出笔记、chunk、embedding、摘要陈旧度、图边、三元组数量等健康指标。
• vault_prediction_errors() / vault_record_usage(note_paths=[...])：前者暴露检索质量差的笔记，后者把被真正使用过的笔记通过"热度"分数拉高，影响后续排序 资料来源：[src/neurostack/skills/vault-audit.md:5-30](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/skills/vault-audit.md)。

使用模式与选型决策树

skills 文档给出了一条清晰的检索选型路径 资料来源：[src/neurostack/skills/vault-search.md:13-30](https://github.com/Abhinav1234abhinav/neurostack/blob/bf2da77a165d5b0acc0a935a3953281085c26008/src/neurostack/skills/vault-search.md)：

1. 需要具体事实 → vault_triples 或 vault_search(depth="triples")
2. 需要主题概览 → vault_search(depth="summaries")
3. 需要真实内容 → vault_search(depth="full")
4. 宽泛/主题性问题 → vault_communities
5. 需要带引用的答案 → vault_ask
6. 探索某条笔记的连接 → vault_graph
7. 寻找相似笔记 → vault_related
8. 检索 agent 写下的"记忆" → vault_memories

调用方只需先执行 from neurostack.tools import ensure_registered; ensure_registered()，随后即可通过任一适配器（OpenAI function-calling、REST POST /v1/tools/{name}、CLI）拿到同名同语义的工具，避免在每个入口重复定义。

See Also

• Configuration & Vault Root
• Embedding & Index Pipeline
• Skills and Prompt Library

数据层、Schema 与知识图谱

概览

neurostack 的数据层承担着"第二大脑"的核心职责：把本地 Markdown 笔记、嵌入向量、知识三元组、记忆条目与社区结构统一持久化到 SQLite 中，供上层检索、RAG 问答与 AI 代理调用。整套系统在 src/neurostack/__init__.py:5-6 中被定位为"AI-provider-agnostic, neuroscience-grounded knowledge management"——一个与具体 AI 提供方解耦、以神经科学启发的记忆模型为底层隐喻的知识管理系统。

数据层的关键设计目标是本地优先、可增量更新、兼容 Lite 模式。在 npm/README.md:21-26 中明确区分了两种安装模式：

Lite 模式下 numpy 等可选依赖不会被拉入，因此诸如 attractor.py 中的社区检测会显式抛出 ImportError 提示用户安装 neurostack[full]。资料来源：src/neurostack/attractor.py:1-25。

数据库 Schema

所有数据通过 SQLite 存储在由 src/neurostack/schema.py 中 DB_PATH 指向的本地文件中，并在 src/neurostack/tools/search_tools.py 的 vault_summary / vault_search 等工具中通过 get_db(DB_PATH) 取得连接。主要表与职责如下：

嵌入向量以 BLOB 形式落盘；读取时通过 blob_to_embedding(r["embedding"]) 反序列化为 numpy 数组，支撑后续余弦相似度与 PageRank 计算。资料来源：src/neurostack/attractor.py:42-55。

嵌入与文本分块

笔记在入库前会经过 src/neurostack/chunker.py 的分块器按 heading_path 切片，再交由 src/neurostack/embedder.py 调用的嵌入服务向量化。结果既可直接用于 hybrid_search 的稠密检索，也会按 note_path 聚合为笔记级向量，以驱动 src/neurostack/related.py 中的 find_related()，发现未显式链接但语义相近的笔记。

RAG 问答流程在 src/neurostack/ask.py 中串起整条管线：hybrid_search 取出前 top_k 个相关片段 → 构造 [Title] (path): snippet 形式的 source block → 拼接 ASK_PROMPT → 调用与 OpenAI 兼容的 /v1/chat/completions（temperature=0.3、max_tokens=500）→ 去除 <think> 噪声后返回带 [[note-title]] 内联引用的答案。

flowchart LR
    A[Markdown 笔记] --> B[chunker.py<br/>按 heading 切片]
    B --> C[embedder.py<br/>向量化]
    C --> D[(chunks.embedding<br/>BLOB)]
    A --> E[schema.py<br/>notes / triples]
    D --> F[hybrid_search /<br/>tiered_search]
    E --> G[attractor.py<br/>吸引子动力学]
    F --> H[ask.py<br/>RAG 问答]
    G --> H

知识图谱与社区检测

知识图谱由三种边共同构成：显式 Wiki 链接（in_degree / out_degree 反映在 notes 表）、从笔记中抽取的 SPO 三元组（triples 表，被 vault_triples 以约 10-20 token/事实的紧凑形式返回，资料来源：src/neurostack/tools/search_tools.py:1-20）、以及实体共现权重（entity_cooccurrence 表，由 src/neurostack/cooccurrence.py 从三元组派生）。

社区检测由 src/neurostack/attractor.py 实现：先融合嵌入相似度、共现权重与 Wiki 链接得到混合相似矩阵，再分别以 β=0.5（粗）与 β=2.0（细）两档温度参数运行吸引子动力学，清除已有社区后做全量重建，最终将收敛到的吸引子盆分配给各笔记。重建时若 len(note_paths) < 3 会跳过并打 warning。资料来源：src/neurostack/attractor.py:1-55。

对外暴露的检索工具按成本由低到高形成清晰的选择阶梯，vault_search(depth="triples"|"summaries"|"full"|"auto") 决定读取深度，vault_graph 用于沿显式链接做邻居遍历并附带 pagerank 分数，vault_related 走嵌入相似度发现隐式连接，vault_communities 则面向全局主题性问题（GraphRAG，最贵）。这一决策树已沉淀在技能说明 src/neurostack/skills/vault-search.md 中，供 AI 代理按需选用。

常见失败模式

• Lite 模式运行社区检测：会触发 ImportError("Community detection requires numpy. Install with: pip install neurostack[full]")（src/neurostack/attractor.py:8-13）。
• 没有嵌入的块：attractor.py 检测到 chunk_rows 为空时记 warning 并 return 0, 0，不会创建社区。
• 笔记过少：少于 3 个已嵌入笔记时同样跳过社区检测。
• RAG 无命中：ask.py 在 hybrid_search 返回空时直接返回 "No relevant notes found in the vault." 而非调用 LLM，避免幻觉。资料来源：src/neurostack/ask.py:1-25。

参见

• 搜索与检索工具
• AI 代理集成（MCP / OpenAI / REST）
• 配置与模式（full / lite）

部署、云同步与可扩展性

NeuroStack 是一个本地优先的 AI 知识库工具，其部署、云同步与可扩展性三个维度共同构成了从单机使用到多端协作、从基础功能到多协议集成的完整链路。__init__.py 中将项目定位为「AI 提供商无关、神经科学启发的知识管理」工具，版本号 0.10.1 资料来源：src/neurostack/__init__.py:5-9。

1. 部署：双通道安装与模式选择

NeuroStack 提供两条主要部署通道：Python 源码直接运行 与 npm 包装器。package.json 中定义了 bin 字段，注册 neurostack 与 ns 两个命令，并通过 postinstall / preuninstall 钩子自动处理 Python 虚拟环境的创建与清理 资料来源：npm/package.json:3-15。

npm 包装器要求环境为 Linux 或 macOS、Python 3.11+（需启用 SQLite FTS5）、git 与 curl，安装器会自动安装 uv、克隆代码库并建立 venv 资料来源：npm/README.md:17-25`。项目同时支持两种运行模式：

若启用 Full 模式的 Ollama 后端，还需手动拉取嵌入模型 nomic-embed-text 与生成模型 qwen2.5:3b 资料来源：npm/README.md:27-33。这意味着用户可以按算力与隐私需求灵活裁剪部署范围。

2. 云同步：基于内容哈希的增量同步

云同步功能位于 src/neurostack/cloud/ 子包，对应 CLI 的 neurostack cloud push/pull/query 命令；服务端基础设施独立于 neurostack-cloud 包 资料来源：src/neurostack/cloud/__init__.py:1-9。

2.1 清单与差异计算

Manifest 类通过扫描 vault 根目录为每个 .md 文件计算 SHA-256 哈希，生成 相对路径 → 哈希值 的映射表，并提供 scan_vault() 与 SyncDiff 工具来识别新增、变更与删除的文件 资料来源：src/neurostack/cloud/manifest.py:23-58。SyncDiff.upload_files 属性返回需要上传的文件集合，避免重复传输未变更内容。

2.2 同步引擎与配置

VaultSyncEngine 使用 httpx 进行 multipart 上传、状态轮询与流式下载，所有 HTTP 调用均带 Bearer 认证头 资料来源：src/neurostack/cloud/sync.py:17-48。其构造参数 poll_interval（默认 5.0 秒）与 poll_timeout（默认 3600.0 秒）控制索引轮询行为。配置加载遵循 默认值 → config.toml [cloud] 节 → 环境变量 的三层优先级，其中 NEUROSTACK_CLOUD_API_URL 与 NEUROSTACK_CLOUD_API_KEY 可作为最高优先级覆盖 资料来源：src/neurostack/cloud/config.py:42-71。

flowchart LR
    A[本地 Vault<br/>.md 文件] --> B[Manifest.scan_vault<br/>SHA-256 哈希]
    B --> C{SyncDiff<br/>差异计算}
    C -->|added/changed| D[VaultSyncEngine<br/>multipart 上传]
    C -->|removed| E[记录删除]
    D --> F[云端索引器]
    F --> G[轮询状态<br/>poll_interval=5s]
    G --> H[下载索引 DB]
    H --> I[远程查询]

3. 可扩展性：统一注册表与多协议适配器

NeuroStack 的核心可扩展性来源于 工具注册表（registry）与三类适配器，它们把同一套内部函数暴露给不同协议消费方：

• REST 适配器：create_tools_router(prefix="/v1/tools") 创建 FastAPI 路由，自动生成 GET /v1/tools（列出所有工具及参数 schema）与 POST /v1/tools/{tool_name}（调用工具）端点 资料来源：src/neurostack/tools/rest_adapter.py:9-37。
• OpenAI 适配器：get_openai_tools() 把注册表中的工具转换为 OpenAI function calling 格式（截断 docstring 至 1024 字符），execute_tool_call() 反向解析 function call 并执行 资料来源：src/neurostack/tools/openai_adapter.py:31-65。
• MCP 适配器：create_mcp_server(name="neurostack") 通过 FastMCP 自动包装所有工具函数，保留原函数签名与 docstring，可通过 mcp.run(transport="stdio") 启动 资料来源：src/neurostack/tools/mcp_adapter.py:17-34。

三类适配器共享同一注册表（ensure_registered()），新增工具只需通过 @registry.tool(tags=[...]) 装饰器声明，即可在 REST、OpenAI、MCP 三种协议下同时可用——这是项目支持任意 AI 提供商的关键机制。

4. 常见失败模式

• Windows 原生安装受限：package.json 的 os 字段仅声明 ["linux", "darwin"]，Windows 用户需通过 WSL 或 Python 源码方式部署 资料来源：npm/package.json:34-36。
• 同步清单路径错位：若 vault 根目录包含被忽略的子目录，scan_vault() 需正确处理 relative_path 的统一分隔符，否则哈希会因路径表示差异而失配。
• 云端凭据残留：clear_cloud_credentials() 仅清空 cloud_api_key 而保留 cloud_api_url，切换账户时需注意 URL 是否仍指向原租户 资料来源：src/neurostack/cloud/config.py:23-31。

See Also

• README.md — 项目总体说明
• src/neurostack/skills/vault-search.md — 检索策略与工具选择
• src/neurostack/skills/memory-management.md — 记忆管理 API

Pitfall Log / 踩坑日志

项目：Abhinav1234abhinav/neurostack

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

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

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

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

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

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

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

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

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

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

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

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