Content
# NOUZ — Semantic MCP Server for Your Knowledge Base
> *Structure emerges from content.*
Works with Obsidian, Logseq, and any directories of Markdown files.
[](LICENSE)
[](https://python.org)
[](https://modelcontextprotocol.io)
[](https://pypi.org/project/nouz-mcp/)
🇬🇧
## Why NOUZ
NOUZ acts as an intermediary between your note repository and AI agent. It helps transform scattered Markdown files into a graph that's convenient for both you and the agent:
1. **Automatic Classification (Semantics)**
You define "Cores" — the basic domains of your repository. 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 constructs a directed structural graph: `hierarchy` is maintained as a DAG without cycles, and additional semantic connections live alongside:
- *Semantic Bridges:* Two notes from different domains point to the same idea.
- Explicit tag connections can be stored manually in YAML.
3. **Tracking Base Evolution (Drift)**
NOUZ stores the domain profile of content nodes and can compare it with the declared sign. If a module is described as one domain but its profile gradually shifts to another, the server will show the discrepancy (`core_drift`).
Depending on your tasks, NOUZ operates 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 by what text features it's recognized.
2. The server converts descriptions into vector etalons (locally, through LM Studio, or Ollama).
3. Each new note is projected onto these axes. The sign is determined by content or by you.
It's essential to separate two layers here. `artifact_signs` describe the form of L5 artifacts: log, source, hypothesis, specification, etc. These signs are not aggregated into a domain sign L4. A log remains a log, and a source remains a source.
`core_mix` is not a sum of artifact types. It's a domain profile in the SQLite index. L4/L3/L2 receive it from their own text during `recalc_signs`, and parent nodes can then obtain an averaged profile of child content nodes through `recalc_core_mix`. `core_drift` appears when the saved domain profile and current `sign` point to different leading domains.
**Semantic Bridges** find connections between notes from different domains when texts are close in meaning. If chunks already exist for both notes, the bridge is additionally verified by the best pair of them and returns a specific feature. Tags remain explicit user markup.
## Quick Start
```bash
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:
```bash
cp config.template.yaml config.yaml
```
In Windows PowerShell:
```powershell
Copy-Item config.template.yaml config.yaml
```
Or from sources:
```bash
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:
```json
{
"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
| Tool | Purpose |
|-------|---------|
| `suggest_metadata` | Sign, level, bridges, drift warnings |
| `write_file` | Write a note with YAML markup |
| `update_metadata` | Update only YAML, without changing the note text |
| `read_file` | Read a note + metadata |
| `calibrate_cores` | Update core etalons |
| `recalc_signs` | Recalculate signs of all notes |
| `recalc_core_mix` | Recalculate the domain profile of parents based on child content nodes |
| `index_all` | Reindex the entire base; in PRIZMA/SLOI with `with_embeddings=true` also updates file/chunk embeddings |
| `embed` | Get a vector for text in PRIZMA/SLOI |
| `chunk_text` | Cut Markdown text into stable chunks in PRIZMA/SLOI |
| `chunk_file` | Cut the body of a single note into stable chunks in PRIZMA/SLOI |
| `search_chunks` | Search by saved chunk embeddings in PRIZMA/SLOI; by default, reduces anisotropy |
| `list_files` | List with filters by level, sign |
| `get_children` | Traverse down the graph |
| `get_parents` | Traverse up the graph |
| `suggest_parents` | Find parents for an orphan |
| `add_entity` | Create an entity in one step (automatic sign and hierarchy, tags only explicitly) |
| `process_orphans` | Autofill files without markup |
## Configuration
Minimal `config.yaml`:
```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 configuring, run `calibrate_cores` — the server will create etalon vectors.
Check pairwise cosines: mean-centered between different domains should be noticeably lower than the original. If all pairs are approximately the same — enhance differences in texts.
Separate verification of etalons can be launched from the installed package:
`nouz-calc-etalons --config config.yaml`.
`etalons` are semantic domains compared through embeddings.
`artifact_signs` are the type of material for L5 artifacts: note, concept, reference, log, update, hypothesis, or specification. This is a heuristic label. Domains are usually denoted by capital letters (`S/D/E`), and material types are denoted by lowercase letters (`n/c/r/l/u/h/s`); they can be replaced in the config with any other values. If necessary, for any type, you can add `keywords`: 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 the S/D/E benchmarks with the `text-embedding-granite-embedding-278m-multilingual` model:
```text
=== 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. Smoke test benchmarks with the current `nouz-calc-etalons`: S→99.6%, D→98.5%, E→98.1%. This is not an assessment of the entire database, but a quick check that each benchmark confidently returns to its sign after the same centering.
| Variable | Default | Description |
| --- | --- | --- |
| `OBSIDIAN_ROOT` | `./obsidian` | Path to storage |
| `NOUZ_CONFIG` | *(empty)* | Absolute path to `config.yaml`; if not specified, the server searches for the config in the current directory |
| `NOUZ_DATABASE_NAME` | `obsidian_kb.db` | Name of the SQLite cache file within `OBSIDIAN_ROOT`; convenient for isolated checks, e.g., `obsidian_kb.public.db` |
| `NOUZ_DATABASE_PATH` | *(empty)* | Full path to the SQLite cache; takes priority over `NOUZ_DATABASE_NAME` |
| `EMBED_PROVIDER` | `openai` | `openai`, `lmstudio`, `ollama` |
| `EMBED_API_URL` | `http://127.0.0.1:1234/v1` | Endpoint for embeddings |
| `EMBED_API_KEY` | *(empty)* | API key, if required |
| `EMBED_MODEL` | *(empty)* | Model name |
---
## Privacy
| Component | Local? |
|-----------|-----------|
| Embeddings (LM Studio / Ollama) | ✅ Yes |
| Your notes | ✅ Yes |
| NOUZ server | ✅ Yes |
| AI agent context (Claude, ChatGPT) | ❌ Goes to the cloud |
Everything critical remains on your machine.
---
## Development
```bash
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
```
---
## Links
- 🌐 [semiotronika.ru](https://semiotronika.ru)
- 📦 [PyPI](https://pypi.org/project/nouz-mcp/)
- 🗂️ [Glama Registry](https://glama.ai/mcp/servers/Semiotronika/NOUZ-MCP)
- 🐙 [GitHub](https://github.com/Semiotronika/NOUZ-MCP)
MIT License 2026 Semiotronika
*Cosines are calculated. Syntax changes. Semantics remain.*
<!-- mcp-name: io.github.Semiotronika/NOUZ-MCP -->
