NOUZ — Semantic MCP Server for your knowledge base

Works with Obsidian, Logseq, and any directory of Markdown files.

Structure emerges from content.

Semantic tools for knowledge bases, project memory, and AI agents.

🇬🇧 English version

Why Nouz is needed

Folders show where a file is located. But they don't explain to an agent how documents, ideas, and materials within the base are connected.

NOUZ gives the agent semantic coordinates. Each note receives a domain sign, a level in the hierarchy, and links to other notes. The domain is assigned based on the file's content, or manually by you if you want a strict hierarchy.

Related MCP server: Semantic Mesh Memory (SEM) MCP Server

What it does

NOUZ acts as a layer between your note base and an AI agent. It helps turn scattered Markdown files into a graph that can be worked with via MCP:

1. Automatic Classification (Semantics) You define "Cores" — the base domains of your database (e.g., Systems Analysis, Data & Science, Engineering). When you add a new note, NOUZ reads its text, compares vectors, and suggests a domain sign or a combination of domains.

2. Finding connections between notes The server builds a directed acyclic graph (DAG) and suggests connections that can be verified before saving:

   • Semantic bridges: two notes from different domains point to the same idea.

   • Tag bridges: notes have common hidden concepts at the tag level.

3. Tracking database evolution (Drift) NOUZ aggregates data from the bottom up. If a module started as one domain, but new notes gradually lead it to another, the server will show a discrepancy (core_drift).

Depending on your tasks, NOUZ works in three modes: from a simple graph (LUCA) to a strict 5-level hierarchy (SLOI).

How it works

1. You describe domains in config.yaml — what area each domain covers and what text features to recognize it by.

2. The server turns descriptions into reference vectors (locally, via LM Studio or Ollama).

3. Each new note is projected onto these axes. The sign is determined by content, or by you.

4. L4 receives a domain profile from text classification, and L3/L2 collect core_mix from child nodes. If a module's sign diverges from core_mix, the server reports a core_drift.

Two types of bridges find connections between notes from different domains: semantic (texts are close) and tag-based (concepts overlap).

Quick start

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

Without config.yaml, the server starts in LUCA mode — a graph without semantics, works immediately.

To enable semantic mode, create a local config from the template:

cp config.template.yaml config.yaml

In Windows PowerShell:

Copy-Item config.template.yaml config.yaml

Or from source:

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

Connecting to Claude Desktop, Cursor, Opencode, or any MCP client:

{
  "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 Tools

Configuration

Minimal 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.

After configuration, run calibrate_cores — the server will create reference vectors. Check pairwise cosines: mean-centered between different domains should be significantly lower than raw. If all pairs are roughly the same, strengthen the differences in the texts.

etalons are semantic domains compared via embeddings. artifact_signs are material types for L5 artifacts: note, concept, link, log, update, hypothesis, or specification. This is a heuristic label, not a separate reference for embeddings. In the public schema, domains are usually denoted by uppercase letters (S/D/E), and material types by lowercase (n/c/r/l/u/h/s); these can be changed in the config if signs are short and do not conflict with domains. If necessary, you can add keywords for any type: then the server will use your words for heuristics instead of the built-in RU/EN set.

Real calculation example

Here are the actual results for S/D/E etalons with the text-embedding-granite-embedding-278m-multilingual model:

=== 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

Negative mean-centered values here are a good result: after subtracting the mean vector, the domains diverge well. Self-classification: S→99.4%, D→97.5%, E→96.9%.

Privacy

Everything critical stays on your machine.

Development

git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -e .
python test_server.py

Links

• 🌐 semiotronika.ru

• 📦 PyPI

• 🗂️ Glama Registry

• 💬 Telegram

• 🐙 GitHub

MIT License © 2026 Semiotronika

Cosines are calculated. Syntax changes. Semantics remain.