内容
秘术
个人知识库（Personal Knowledge Base）MCP服务器。
Andrej Karpathy的LLM Wiki方式鉴，markdown知识库作为单一真实来源，ClaudeRAG-lite重复利用上下文，依照分类约定生成产物，不使用嵌入式。配置驱动环境，允许不同用户扩展。
## 为什么创建
现有方法与工作符。
- **基于向量数据库的RAG**：复制到向量数据库中markdown分离，嵌入式向量数据库 + 嵌入式/摘要模型）常态负担大。
- **工具内置维基（git-ignored）**：Karpathy模型，但存储位置在工具移动设备/Obsid同步断开连接。
将用户的markdown知识库真实来源。保留Ob + git同步工作流额外嵌入式基础设施。
## 核心原则
1.来源是markdown知识库到其他存储库。
使用嵌入式，由Claude（Kar将搜索委托给LL）负责。索引使用TS5。
3.边界 = 拉取阻止推送允许。阻止路径（配置文件`boundary.locked_dirs_dirs` + 代码硬守卫`HardLockedDirs未注册目录故障安全）从搜索/索引/排除，但允许写入式单条读取。异常（分类未注册默认阻止（私有）**，仅通过笔记前置`ai_access: shared式（选择加入）`HardLockedDirs`或编辑错误时的网。
4. 可 = 引擎固定 +化（`kb.config不同用户只需更换配置文件。
5. 前置存在时使用，不存在路径/标题/正断（备用），渐回填。
## 技术栈
| 组件 | 选择 |
---|
| 语言/ Go（单个二进制文件go） |
| stdio per-session |
| MCP | 官方`model-sdk` v6.1 |
| 索引 | `modernc.org/sqlite` FTS5（纯Go） |
| 前置元数据 | `gopkg.in/yaml.v3` |
| glob | `bmatcuk/doublestar/v4` |
> 从Bun + TypeScript开始，因内存/部署到Go。依据测见[docs/design.md](./docs/design.md) §## 结构
```
grimoire/
kb.config.example.json # KB设置模板（复制为kb.config.json；实际设置被gitignore）
.md / docs/design.md/configuration.md # 说明背景/路径·架指南
cmd/
grimoire/ # stdio MCP服务器（启动 周期性mtime增）
reindex # 完整重新索引验证/恢复）
ire-context/ # SessionStart钩子用上下文注入可选）
lint/批量健康检查CLI（Ollama不需要）
/
config/ 和验证kb.config.json boundary/ # AI访问边界守卫（拉/推送允许）
/ # 前置解析 + 备用推断
index/ # SQLite FTS5索引 + 索引器（重新索引/同步）
writer/ # write_note：分类逆映射·文件名·前置元数据·原子写入·编辑
contextsig/ # cwd → jump注册表逆映射（项目推断）
compiler/ # lint（结构检查）+ suggest/apply（前置元数据回填）
ollama/ # 可选Ollama客户端（生成专用，默认禁用）
bin/ # 构建产物（gitignore）
```
## 配置
```bash
cp kb.config.example.json kb.config.json
# 修改kb.config.json的kb.root为个人KB路径，taxonomy/boundary为个人目录结构
mkdir -p ~/memo # KB根目录由config.Load仅验证存在（不自动创建）→ 预先创建
```
实际`kb.config.json`包含个人路径/结构，因此被gitignore。存储库中仅提交通用模板`kb.config.example.json`。`~/memo`等作者环境特有的目录约定仅为示例，用户通过配置文件定义自己的KB结构。
> **路径指定·目录脚手架规则详见[docs/configuration.md](./docs/configuration.md)**。KB根目录（`kb.root`）和配置文件路径GRIMOIRE_CONFIG`层结构区分，taxonomy文件夹声明规则，未注册目录故障安全，`HardLockedDirs`移植注意事项，初始设置流程均有整理，并附有代码依据。
## 构建 / 运行
```bash
# 构建
go build -o bin/grimoire ./cmd/grimoire # MCP服务器时增量同步）
go build -o bin/re ./cmd/reindex 完整重新索引CLI/恢复）
goo bin/grimoire-context/grimoire-context # 会话开始钩（可选）
go build -o bin/lint ./int # 健康检查CLI（Ollama不需要# 完整重新索引 + 验证统计输出（索引恢复路径）
./bin kb.config.json
服务器（stdio）直接运行 — 启动时按mtime部分同步
./bin/grimoire kb.config.json
启动索引是**的增量同步**保存在磁盘上，仅更新变更的笔记（删除会被清除），因此启动时间和空闲内存消耗都很低。启动后，`index.sync_interval_seconds`（默认为）周期性后台增量同步，确保Obsidian等会话中新添加、修改或私有转换（`ai_access`）的笔记无需被反映（与_note`等互斥锁序列化；负值 =周期同步）。如需索引，请使用`` CLI。
## 注册Claude Code
```bash
mcp add grimoire -- ~/tools/grimo/grimoire ~/tools/grimoire/kb.config```
配置文件**文件**路径通过CLI参数或`GRIMOIRE_CONFIG`环境变量指定（参数优先）。笔记**根目录**在配置文件中通过`kb.root`指定 — 两者的路径层次区别详见[docs/configuration.md §2](./docs/configuration.md#2-两个路径层次的核心区分)。
## MCP工具
| 工具 | 功能 | 阻止路径 |
|---|---|---|
| `get_index` | 目录（标题·标签·摘要·路径）路由用 | 排除 |
| `search` | FTS5关键词 + 标签/目录过滤 | 排除 |
| `read_note` | 正文读取 | 显式单条允许 |
| `links` | `[[链接]]`图（出入链） | 排除 |
| `write_note` | 分类约定存储（逆映射·前置元数据·原子写入·编辑） | 写入允许 |
| `get_context` | cwd→项目逆推 + 相关手册·笔记候选 | 排除 |
| `get_runbook` | 重复过程（`type:runbook`）返回 | 排除 |
| `lint` | 健康检查（前置元数据缺失/悬挂链接）— Ollama不需要 | 排除 `suggest_frontmatter` | Ollama前置元数据回填建议（应用时仅记录缺失键） | 排除/拒绝 |
## 用法（工作流）
工具由Claude Code自动调用。以下是各流程的意图和触发示例。
### 1) 上下文查询（RAG-lite）
搜索主体是Claude。通过`get_index`/`search`获取KB地图，选择要读取的页面，然后使用`read_note`读取正文，使用`links`跟踪连接的笔记。
```
"sre指南中找dev集群安装流程并 → search({dev集群安装", dir:"sre-guides"}) → read_note(...)
```
### 2) 产物存储（write_note）
按分类约定将分析/文档存储在指定位置。按`type`/`domain`逆映射目录（或直接指定`dir`），自动生成文件名和前置元数据。
```
"将此分析存储为backend分析"
→ write_note({title, content, type:"analysis", domain:"backend"})
→ backend/<topic>-<detail>.md 含前置元数据存储
```
若分类不明确，则返回`ok:false` + 候选目录。`:true`目录（例如`personal-blog`）若混入内部标识符，则拒绝存储。
### 3) 运行手册：重复流程一次性编写 → 每次调用
像部署、集群连接这样的重复流程，可以用`type:runbook`**一次性**编写，以后Claude通过`get_runbook`调用该重复利用）。
```
# （一次性）编写运行"将proj-a部署流程整理为运行手册。包含alpha/beta kubeconfig路径和部署命令"
→ write_note({title:"proj-a部署运行手册", type:"runbook", tags:["proj-a","deploy"], content:...})
→ runbooks/proj-a-deploy.md
# （后续）调用
"进行proj-a alpha部署"
→ get_runbook({name:"proj-a"}) → 获知运行手册内容（流程·注意事项）后进行```
> `get_runbook`仅查看`type:runbook`笔记。如果当前KB中运行手册数量为0，则返回空列表，因此需先进行上述**一次性**编写。`runbooks`目录在配置文件`taxonomy.directories`中定义，`type:runbook`写入会映射到该目录。
### 4) 工作路径上下文（get_context）
将cwd映射到jump注册表（`context_signals.jump_registry`），推断出项目，并缩小相关运行手册和笔记的范围。即使用户不明确指出项目，也能获取上下文。
```
get_context({cwd:"/Users/you/projects/proj-a"})
→ 推断 project:"proj-a" → 返回相关runbooks/notes候选
```
若信号源缺失或匹配失败，则返回`enabled:false`/空候选，路由仅依赖显式`scope`参数。
#### （可选）会话开始自动注入
将`bin/grimoire-context`连接到Claude Code的`SessionStart`钩子，会话开始时自动注入当前工作路径的运行手册和笔记。匹配失败时不输出任何内容。
```jsonc
// ~/.claude/settings.json 的 hooks.SessionStart 添加分组
{ "hooks": [ { "type": "command": "~/tools/grimoire/bin/grimoire-context ~/tools/grimoire/kb.config.json" } ] }
```
### 5) 健康检查 & 前置元数据回填（编译器）
KB增长后，前置元数据缺失和损坏链接会累积。使用`lint`检查，并可选地由Ollama建议前置元数据。
```bash
# 结构健康检查（Ollama不需要）— 报告前置元数据缺失/悬挂链接
./bin/lint kb.config.json # 报告前50个
./bin/lint kb.config.json --all # 报告全部
```
`suggest_frontmatter`（MCP工具）使用Ollama建议前置元数据候选。**默认禁用**，需在配置文件中启用：
```jsonc
"ollama": { "enabled": true, "host": "http://localhost:11434", "model": "qwen3:8b" }
```
```
"请为此笔记补充前置元数据：backend/redis-penetration.md"
→ suggest_frontmatter({path:"backend/redis-penetration.md"}) # 仅建议（用于审核）
→ suggest_frontmatter({path:"...", apply:true}) # 审核后记录
```
安全措施（设计§11）：
- **建议 → 审核 → 记录**`apply:true`仅插入**缺失的核心键**，绝不覆盖现有键（幂等，原子写入）。
- 文件名中没有日期时，不会随机生成`date`。
- 阻止路径不会传递给Ollama，也不会被修改。
- Ollama未运行/禁用时，返回`ok:false`进行优雅处理（引擎其余功能正常）。
> 模型可以使用Ollama上的任意文本生成模型。回填是轻量级的JSON分类，因此可以使用轻量级模型（例如`qwen3:8b`，`gemma3:4b`llama3.2:3b`）。这不是嵌入。
##
功能：RAG-lite 4工具（_index`/`search`/`read_note`/`）+ `write_note`（分类约定存储 增量索引 + `get_context`/`book`（工作路径·运行手册路由）lint`/`suggest_frontmatter`（健康Ollama回填）。
未来（可选文档达到数万级别且探索性问题频繁时，添加嵌入层。
## 许可证
未确定项目）。
