Nouz

NOUZ — 用于知识库的语义 MCP 服务

结构源于内容。

适用于 Obsidian、Logseq 以及任何 Markdown 文件目录。

NOUZ 基于 MCP Python SDK v2 运行。

🇬🇧 English version

---

为什么需要 Nouz

NOUZ 是您的笔记库与 AI Agent 之间的中间层。它可以将零散的 Markdown 文件转换为图谱，方便您和 Agent 使用：

1. 自动分类（语义） 您定义“核心”——知识库的基础领域。添加新笔记时，NOUZ 会读取笔记文本、比较向量，并建议一个领域标记或领域组合。

2. 查找笔记之间的关联 服务会构建有向结构图：hierarchy 保持为无环 DAG，其他语义关联则并存于其中：

   • 语义桥接： 不同领域的两条笔记指向同一个概念。
   • 显式标签关联可以手动存储在 YAML 中。

3. 跟踪知识库的演变（漂移） NOUZ 会保存内容节点的领域配置，并可将其与声明的标记进行比较。如果某个模块被描述为一个领域，但其配置逐渐偏向另一个领域，服务会显示差异（core_drift）。

根据您的需求，NOUZ 支持三种模式：从简单图谱（LUCA）到严格的 5 级层次结构（SLOI）。

---

工作原理

1. 您在 config.yaml 中描述各个领域——每个领域涵盖的范围，以及用于识别文本特征的依据。
2. 服务将这些描述转换为基准向量（本地运行，或通过 LM Studio 或 Ollama）。
3. 每条新笔记都会投射到这些轴上。标记由内容或您来决定。

这里需要区分两个层次。artifact_signs 描述 L5 工件的形式：日志、来源、假设、规范等。这些标记不会聚合为 L4 领域标记。日志始终是日志，来源始终是来源。

core_mix 不是工件类型的总和，而是 SQLite 索引中的领域配置。L4/L3/L2 会在 recalc_signs 时根据自身文本生成该配置；随后，父节点可以通过 recalc_core_mix 获取子内容节点的平均配置。若已保存的领域配置与当前 sign 指向不同的主导领域，就会出现 core_drift。

语义桥接会在不同领域的笔记之间查找关联，判断依据是文本的语义相似度。如果两条笔记都已有分块，桥接还会通过其中最匹配的一对分块进行验证，并返回具体特征。标签仍是明确的用户标注。

---

快速开始

pip install nouz-mcp
OBSIDIAN_ROOT=/path/to/vault nouz-mcp

如果没有 config.yaml，服务会以 LUCA 模式启动——这是一个不含语义的图谱，可立即使用。

如需启用语义模式，请根据模板创建本地配置：

cp config.template.yaml config.yaml

在 Windows PowerShell 中：

Copy-Item config.template.yaml config.yaml

或者从源代码运行：

git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -r requirements.txt
cp config.template.yaml config.yaml
OBSIDIAN_ROOT=./vault python server.py

连接到 Claude Desktop、Cursor、Opencode 或任何 MCP 客户端：

{
  "mcpServers": {
    "nouz": {
      "command": "nouz-mcp",
      "env": {
        "OBSIDIAN_ROOT": "/path/to/vault",
        "NOUZ_CONFIG": "/absolute/path/to/config.yaml",
        "EMBED_API_URL": "http://127.0.0.1:1234/v1"
      }
    }
  }
}

---

Инструменты MCP

Инструмент	Зачем
suggest_metadata	Знак, уровень, мосты, дрифт-предупреждения
write_file	Записать заметку с YAML-разметкой
update_metadata	Обновить только YAML, не меняя текст заметки
read_file	Прочитать заметку + метаданные
calibrate_cores	Обновить векторы-эталоны ядер
recalc_signs	Пересчитать знаки всех заметок
recalc_core_mix	Пересчитать доменный профиль родителей по дочерним содержательным узлам
index_all	Переиндексировать всю базу; в PRIZMA/SLOI с with_embeddings=true также обновляет эмбеддинги файлов/чанков
embed	Получить вектор для текста в PRIZMA/SLOI
chunk_text	Разрезать Markdown-текст на стабильные чанки в PRIZMA/SLOI
chunk_file	Разрезать тело одной заметки на стабильные чанки в PRIZMA/SLOI
search_chunks	Искать по сохранённым chunk embeddings в PRIZMA/SLOI; по умолчанию снижает анизотропию
list_files	Список с фильтрами по уровню, знаку
get_children	Пройти вниз по графу
get_parents	Пройти вверх по графу
suggest_parents	Найти родителей для сироты
add_entity	Создать сущность в один шаг (автоматический знак и иерархия, теги только явно)
process_orphans	Автозаполнение файлов без разметки

---

Конфигурация

Минимальный config.yaml:

mode: prizma

etalons:
  - sign: S
    name: Systems Analysis
    text: >
      Methodology for analysing complex objects: feedback loops,
      emergent properties, self-regulation, bifurcation points.
      Cybernetics, synergetics, dissipative structures, catastrophe
      theory, autopoiesis — tools for understanding how the whole
      exceeds the sum of its parts. Not data and not code — a way
      of thinking about how parts form a whole and why systems
      behave non-linearly.
  - sign: D
    name: Data & Science
    text: >
      Physics and cosmology: from subatomic particles to the large-scale
      structure of the Universe. Lagrangians, curvature tensors, scattering
      cross-sections, quarks, bosons, fermions, plasma, vacuum fluctuations,
      cosmic microwave background, cosmological constant, decoherence.
      Pure science about the nature of matter, energy and spacetime.
  - sign: E
    name: Engineering
    text: >
      Software engineering, machine learning and infrastructure: writing
      and debugging code, deployment, containerisation, neural networks,
      inference, tokenisation, data serialisation, microservices, CI/CD,
      automated testing, refactoring, Git, Docker, Kubernetes, APIs.
      The practical discipline of building computational systems from
      architecture to production.

thresholds:
  sign_spread: 0.05
  confident_spread: 60.0
  pattern_second_sign_threshold: 30.0
  semantic_bridge_threshold: 0.55
  parent_link_threshold: 0.55

artifact_signs:
  - sign: n
    name: Note
    text: Short note, observation, fragment.
  - sign: c
    name: Concept
    text: Definition, concept, entity description.
  - sign: r
    name: Reference
    text: External source, documentation, link, citation.
  - sign: l
    name: Log
    text: Session log, chronology, dialogue record.
  - sign: u
    name: Update
    text: Update, release note, changelog entry.
  - sign: h
    name: Hypothesis
    text: Hypothesis, assumption, speculative idea.
  - sign: s
    name: Specification
    text: Technical specification, instruction, requirements.

После настройки запустите calibrate_cores — сервер создаст эталонные векторы. Проверьте попарные косинусы: mean-centered между разными доменами должен быть заметно ниже исходного. Если все пары примерно одинаковые — усильте различия в текстах. Отдельную проверку эталонов можно запустить из установленного пакета: nouz-calc-etalons --config config.yaml.

etalons — это смысловые домены, которые сравниваются через эмбеддинги. artifact_signs — тип материала для артефактов L5: заметка, концепт, ссылка, лог, обновление, гипотеза или спецификация. Это эвристическая метка. Домены обычно обозначаются заглавными буквами (S/D/E), а типы материала — строчными (n/c/r/l/u/h/s); их можно заменить в конфиге на любые другие значения. При необходимости для любого типа можно добавить keywords: тогда сервер будет использовать ваши слова для эвристики вместо встроенного RU/EN набора.

Реальный пример расчёта

Вот фактические результаты для эталонов S/D/E с моделью text-embedding-granite-embedding-278m-multilingual:

=== Pairwise Cosine (raw) ===
S↔D: 0.5894    S↔E: 0.5862    D↔E: 0.6022

=== Pairwise Cosine (mean-centered) ===
S↔D: -0.5059   S↔E: -0.5117   D↔E: -0.4822

Отрицательные mean-centered значения здесь хороший результат: после вычитания среднего вектора домены хорошо расходятся. Smoke test эталонов текущим nouz-calc-etalons: S→99.6%, D→98.5%, E→98.1%. Это не оценка всей базы, а быстрая проверка, что каждый эталон после того же центрирования уверенно возвращается к своему знаку.

Переменная	По умолчанию	Описание
OBSIDIAN_ROOT	./obsidian	Путь к хранилищу
NOUZ_CONFIG	(пусто)	Абсолютный путь к config.yaml; если не задан, сервер ищет конфиг в текущей директории
NOUZ_DATABASE_NAME	obsidian_kb.db	Имя файла SQLite-кэша внутри OBSIDIAN_ROOT; удобно для изолированных проверок, например obsidian_kb.public.db
NOUZ_DATABASE_PATH	(пусто)	Полный путь к SQLite-кэшу; имеет приоритет над NOUZ_DATABASE_NAME
EMBED_PROVIDER	openai	openai, lmstudio, ollama
EMBED_API_URL	http://127.0.0.1:1234/v1	Эндпоинт для эмбеддингов
EMBED_API_KEY	(пусто)	API-ключ, если нужен
EMBED_MODEL	(пусто)	Имя модели

---

Приватность

Компонент	Локально?
Эмбеддинги (LM Studio / Ollama)	✅ Да
Ваши заметки	✅ Да
Сервер NOUZ	✅ Да
Контекст AI-агента (Claude, ChatGPT)	❌ Уходит в облако

Всё критичное остаётся на вашей машине.

---

Разработка

git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -e .
python -m compileall -q nouz_mcp pytest_smoke.py scripts
python -m pytest -q
python test_server.py

---

Ссылки

• 🌐 semiotronika.ru
• 📦 PyPI
• 🗂️ Glama Registry
• 🐙 GitHub

MIT License © 2026 Maria Belkina

Косинусы считаются. Синтаксис меняется. Семантика остаётся.