stellavault

Claude 记得的本地优先第二大脑。
Karpathy 的自编译 wiki × Zettelkasten — 完全本地化、保障知识库安全，并原生支持 MCP。

English · 한국어 · 日本語 · 简体中文

🤖 添加到 Claude / Cursor · ⬇ 桌面应用 · ⚡ 快速入门 · 🌐 在线演示

只需一条命令，就能让 Claude 读取你的知识库：

npx -y stellavault setup    # 将 MCP 服务接入 Claude Code / Desktop、Cursor、Windsurf 或 VS Code

Claude Code 用户？ 也可以改为安装插件 — 只需两条命令，即可使用 MCP 服务以及 /vault-ask、/vault-review、/vault-decision 技能：

/plugin marketplace add Evanciel/stellavault
/plugin install stellavault@stellavault

会自我编译的第二大脑。 Stellavault 融合了两种关于知识应如何存储和发展的理念：

• 🧠 Karpathy 的自编译 wiki — 添加任何内容（一份 PDF、一个 YouTube 链接、一个突然闪现的想法），它就会自动提取到 raw/，然后编译成由概念和反向链接构成的整洁 _wiki/。知识会随着积累而自行重新编译，而不是在文件夹里逐渐腐朽。
• 🕸️ Zettelkasten — 原子笔记、[[wikilinks]] 和自然涌现的关联，让思想之网（而非文件夹树）成为你思维方式的真正结构。

最终，你将获得一款本地优先的知识工具 — 包含完整的 Markdown 编辑器、3D 神经网络图、混合 AI 搜索和间隔重复记忆衰减机制，并以桌面应用、命令行、Obsidian 插件和能让 Claude 读取整个知识库的 MCP 服务形式提供。无需云端，无需 API 密钥，原始文件也绝不会被修改。

将你的知识库呈现为神经网络。本地优先，无需云端。

目录

亮点 · 为什么选择 Stellavault？ · 安装 · 编辑器 · 处理流程 · 智能功能 · 搜索与排序 · MCP 集成 · 3D 可视化 · 配置 · 性能 · 技术栈 · 安全 · 故障排除

亮点

• 🧠 它会自行编译。 放入 PDF、YouTube 链接或尚未成形的想法——Stellavault 会将其提取到 raw/，然后编译出包含概念和反向链接的整洁 _wiki/。知识会随着增长自行整理。
• 🔍 真正能找到内容的搜索。 混合检索通过 加权 RRF 融合语义、精确关键词（BM25）以及你自己的 [[wikilinks]] / #tags，然后根据 FSRS 记忆模型重新排序，让你实际使用的内容重新浮现。支持 50 多种语言，完全本地运行，无需 API 密钥。
• 🌌 将你的思维呈现在 3D 中。 实时神经图谱（React Three Fiber）——支持按文件夹深入查看的聚类视图、单条笔记的本地图谱、标签叠加，以及两类边线，让你自己的 wikilinks 在视觉上区别于 AI 推断出的相似关系。可扩展至包含 17k 条笔记的完整知识库。让你看见自己所知的脉络。
• 🤖 Claude 可以读取你的整个知识库。 一流的 MCP 服务（21 个工具）：Claude 可通过 Claude Code、Claude Desktop、Cursor、Windsurf 或 VS Code 搜索、提问、起草、检查和分析你的知识。
• ⏳ 它绝不会悄悄遗忘。 FSRS 记忆衰减会提醒你那些即将遗忘的真实笔记，还能检测整个知识库中的知识缺口、矛盾和重复内容。
• 🔒 本地优先，保护知识库，无需密钥。 本地嵌入、设备端向量存储，并且绝不修改你的原始文件。除非你选择共享，否则任何内容都不会离开你的设备。

为什么选择 Stellavault？

大多数工具都让你在写作、搜索和记忆之间做选择。Stellavault 三者兼顾——完全本地运行，并且 Claude 可以读取。

说明

两者并非非此即彼——Stellavault 甚至可以作为插件在 Obsidian 内部运行。保留你的编辑器，添一个大脑。

安装

桌面应用（推荐——一键安装）

提示

下载 → 解压 → 运行 stellavault.exe（Windows）或 stellavault（Linux）→ 选择笔记文件夹 → 完成。

CLI（面向开发者）

npm install -g stellavault    # or: npx stellavault
stellavault init              # Interactive setup (3 min): index vault + connect AI clients
stellavault setup             # Connect to Claude Code/Desktop, Cursor, Windsurf, VS Code (one command)
stellavault graph             # Launch 3D graph in browser

需要 Node.js 20+。运行 stellavault doctor 可诊断问题。

Obsidian 插件

1. 从 stellavault-obsidian 发布页下载 main.js + manifest.json + styles.css
2. 放入 .obsidian/plugins/stellavault/
3. 在“设置” → “社区插件”中启用
4. 在知识库文件夹中运行 npx stellavault graph，启动 API

编辑器

功能齐全的 Markdown 编辑器——媲美 Obsidian。

工作流

Capture ──→ Organize ──→ Distill ──→ Express

Drop anything → auto-extract → raw/ → compile → _wiki/ → draft

灵感来自 Karpathy 的自编译知识架构。

导入 14 种格式

Express：获取知识

stellavault draft "AI" --format blog      # Blog post from your vault
stellavault draft "AI" --format outline   # Structured outline
stellavault draft "AI" --ai              # Claude API enhanced ($0.03)

或者使用桌面应用中的 Express 标签页——输入主题、选择格式，即可生成以知识库内容为依据的草稿。保存到 _drafts/ 并直接编辑。

智能功能（Stellavault 的独特之处）

这些功能在 Obsidian 中不存在——即使安装插件也不行。

搜索与排名

混合检索通过**加权倒数排名融合（RRF）**结合多种信号——专为个人知识库设计，完全本地运行，无需 API 密钥：

• 实体匹配通过模糊子串匹配和标点规范化匹配来解析自然语言查询（适用于韩语／中日韩文字），并设有单文档多样性上限，避免一篇大型笔记占满顶部结果。
• 时效性复用与衰减引擎相同的 FSRS 记忆模型（而非原始文件修改时间）——你即将遗忘的笔记会重新浮现；掌握牢固的常青笔记不会仅仅因为时间久远而被埋没。
• 自适应重排（长期运行的 MCP 服务）会根据当前会话上下文（近期标签／路径）进一步提升结果排名。
• 每项权重都可按知识库或通过环境变量调整——请参阅配置。

MCP 集成（21 个工具）

stellavault setup            # one command → Claude Code, Claude Desktop, Cursor, Windsurf, VS Code
# or, for Claude Code only:
claude mcp add stellavault -- stellavault serve

{
  "mcpServers": {
    "stellavault": {
      "command": "npx",
      "args": ["-y", "stellavault", "serve"]
    }
  }
}

Claude 可以直接搜索、提问、起草、检查和分析你的知识库。搜索会运行 完整的混合检索流程——对语义 + BM25 + 实体链接进行加权 RRF， 再结合 FSRS 时效性和会话自适应重排（请参阅搜索与排名）。

3D 可视化

• 带簇颜色的神经网络图（React Three Fiber）
• 簇视图（默认）——大型知识库会折叠为一个由带标签的簇超节点组成的小型星系；查看器内的 [Cluster | All nodes] 切换控件可在无需重新加载的情况下切换至密集的原始视图，点击超节点可深入查看该簇的成员
• 星座视图（最小生成树星形模式）
• 热力图叠加层 + 时间轴滑块 + 衰减叠加层
• 多重宇宙视图——将你的知识库显示为 P2P 网络中的一个宇宙
• 深色／浅色主题

图谱查看器缩放

3D 图谱渲染器受两个环境变量限制（启动 stellavault graph 之前在环境中设置）：

为什么这些上限很重要。 边的构建会在内联循环中执行 O(n²) 全量两两余弦计算 — n·(n-1)/2 对，每对计算 384 个维度（参见 packages/core/src/api/graph-data.ts 中的 neighbors 循环）。在 cap=3000 时约有 450 万对（构建需要数秒，由 5 分钟的服务端缓存吸收）；提高到 13000 左右则会达到约 8400 万对，构建需要数分钟，还会产生数 GB 的中间数组，导致单线程 Express 处理程序冻结（没有工作线程）。原始“所有节点”路径的开销更大（会跑满整个上限），因此服务端会按视图限制请求的 ?cap（原始视图 ≤ 4000，聚类视图 ≤ 6000，并向下取整），以控制构建成本和缓存基数。

默认聚类视图只是渲染开销低，构建开销并不低。 首次获取任一尚未缓存的视图时，都会在单个线程上执行限定范围的嵌入加载 + O(n²) 余弦计算 + k-means + 力导向稳定过程，导致处理程序停顿数秒。切换视图时，查看器会显示加载状态，避免冷启动构建期间点击操作被悄然忽略。

热力图 — 各聚类的连接密度	时间线 — 查看知识库随时间增长
搜索 — 在图谱中高亮显示语义匹配结果	Multiverse — 将联邦知识库显示为环绕运行的宇宙

立即试用（演示知识库）

npx stellavault index --vault ./examples/demo-vault   # Index 10 sample notes
npx stellavault search "vector database"               # Semantic search
npx stellavault graph                                  # 3D graph visualization

演示知识库包含关于向量数据库、知识图谱、间隔重复、RAG、MCP 等主题的互相关联笔记，可让你立即探索所有功能。

入门指南

桌面应用

1. 下载 → 解压 → 运行
2. 首次启动时，系统会提示你选择笔记文件夹
3. 笔记会显示在侧边栏中 — 点击即可打开
4. 按 Ctrl+P 可快速切换文件
5. 点击标题栏中的 ✦ 打开 AI 面板（语义搜索、统计、草稿）
6. 点击 ◉ 查看 3D 图谱

命令行界面

npm install -g stellavault
stellavault init                          # Setup wizard
stellavault search "machine learning"     # Semantic search
stellavault ingest paper.pdf              # Add knowledge
stellavault graph                         # 3D graph in browser
stellavault brief                         # Morning briefing
stellavault decay                         # What are you forgetting?

键盘快捷键（桌面应用）

快速参考

配置

Stellavault 会读取 ./.stellavault.json（或 ~/.stellavault.json）。搜索排名完全可调，默认值经过合理配置，开箱即用：

{
  "search": {
    "rrfK": 60,
    "weights": { "semantic": 1.0, "bm25": 1.0, "entity": 1.5 },
    "recencyWeight": 0.2,                          // FSRS recency strength; 0 = off
    "entityAliases": { "k8s": ["kubernetes"] }     // synonym / cross-lingual groups (exact-only)
  }
}

环境变量会覆盖配置（并进行安全解析）：

注意：跨语言召回（例如，使用韩语查询找到英文笔记）由多语言嵌入模型自动处理；entityAliases 是针对经过整理的实体图谱（标签 / 双链）和缩写的可选精度增强项。

性能

在合成知识库上测试，典型用例中的所有操作均在 1 秒内完成：

运行自己的基准测试：

node tests/stress.mjs 500     # Test with 500 synthetic documents

关键优化：

• 构建 HNSW 图 — 对 200 个以上文档使用 sqlite-vec KNN（O(n·K·log n)，而非 O(n²)）
• 预归一化向量：将余弦相似度计算转换为单次点积
• 批量加载嵌入（每批 500 个，防止 RAM 溢出）
• 对小型知识库（< 200 个文档）采用上三角暴力计算
• 使用类型化数组，以 O(n) 时间更新 K-Means 质心

技术栈

安全

• 本地优先 — 除非使用 --ai，否则数据不会离开你的设备
• 知识库文件绝不修改 — 索引写入 SQLite，原文件保持不变
• 启用 Electron 沙箱 — 渲染进程以受限的操作系统权限运行
• IPC 路径验证 — 所有文件操作均限制在知识库根目录内
• API 身份验证令牌 — 每个会话独立，仅通过请求头传递（X-Stellavault-Token）。令牌端点仅允许同源访问
• CORS 允许列表 — 默认仅允许 localhost / 127.0.0.1；MCP HTTP 传输需选择启用
• SSRF 防护 — URL 导入时会屏蔽私有 IP
• 端到端加密 — 云同步使用 AES-256-GCM

联邦（实验性，默认关闭）

点对点语义搜索作为一项选择启用的实验性功能提供。默认安装不会加入任何集群，也绝不会共享数据。

显式启用：

# PowerShell
$env:STELLAVAULT_FEDERATION_EXPERIMENTAL = "1"

# bash / zsh
export STELLAVAULT_FEDERATION_EXPERIMENTAL=1

stellavault federate join

启用后，联邦功能会使用 Ed25519 身份和签名信封、相互质询-响应握手、每个信封的重放随机数、握手超时、对等节点速率限制，以及默认仅接收的共享设置（myNodeLevel=0）。在联邦提示词中运行 set-level 1+，即可实际与对等节点共享标题和摘要片段。

警告

升级提示（v0.7.4） — 联邦线路格式从 v2.0 升级到 v2.1（信封级随机数）。v0.7.3 联邦节点不兼容。现有的 ~/.stellavault/federation/sharing.json 文件不会自动降级为更安全的默认值；如果你之前选择启用，请检查 myNodeLevel。

完整详情请参阅 SECURITY.md。

故障排查

stellavault doctor    # Check config, vault, DB, model, Node version

常见问题：

• “找不到命令” → npm i -g stellavault@latest
• “找不到 API 服务器” → npx stellavault graph
• 图谱为空 → stellavault index
• 首次运行缓慢 → AI 模型仅需下载一次，约 30MB

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md 了解如何开始，并参阅 SECURITY.md 负责任地报告漏洞。

许可证

MIT — 提供完整源代码供审计。

链接

• ⬇ 下载桌面应用
• 着陆页
• Obsidian 插件
• npm
• GitHub 发行版
• 安全策略