Skip to main content
Glama
README.md
# KADRAN-H

Local MCP server that steers LLM output out of its statistical average. It protects the task's functional kernel, rejects the domain's stock patterns, and rotates the stylistic orbit toward a cross-domain anchor. The model gets one compact directive instead of another brainstorming loop.

[![CI](https://github.com/Syron01/kadran-h/actions/workflows/ci.yml/badge.svg)](https://github.com/Syron01/kadran-h/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/github/license/Syron01/kadran-h)](https://github.com/Syron01/kadran-h/blob/main/LICENSE)

```text
[HQMS α=0.90 | KEEP:high trust,clear CTA,readable | BAN:Purple Blue Gradient,Glassmorphism Cards,3D Hero Blob | ANCHOR:Transit Wayfinding × Border Crossing File | HASH:e368816e5733c3ab]
```

That directive is real output from `npm run samples`. It is 22 tokens. The server makes no network calls, calls no LLM, and does not store prompts or completions. Its local store keeps hashes, anchor labels, and coarse telemetry.

## Quickstart

Node.js 20 or newer.

```bash
git clone https://github.com/Syron01/kadran-h.git
cd kadran-h
npm ci
npm run build
```

Point your MCP client at the built server:

```json
{
  "mcpServers": {
    "kadran-h": {
      "command": "node",
      "args": ["/absolute/path/to/kadran-h/dist/mcp/server.js"]
    }
  }
}
```

| Client | Config file |
| :--- | :--- |
| Claude Desktop | `claude_desktop_config.json` in the Claude Desktop settings directory |
| Claude Code | project `.mcp.json` or user-level `~/.claude.json` |
| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
| Gemini CLI | `~/.gemini/settings.json` |

Install the skill so the agent knows when to call the server:

| Client | Skill path |
| :--- | :--- |
| Claude Code | `.claude/skills/kadran-h/SKILL.md` |
| Cursor | `.cursor/skills/kadran-h/SKILL.md` |
| Gemini CLI | `.gemini/skills/kadran-h/SKILL.md` |

```bash
mkdir -p .claude/skills/kadran-h
cp skills/kadran-h/SKILL.md .claude/skills/kadran-h/SKILL.md
```

> [!TIP]
> Use `alpha=0.9` when the user asks for something original. Keep `alpha=0.5` for adjacent exploration, and `0.0` when the existing direction is already right.

## Tools

| Tool | Input | Returns |
| :--- | :--- | :--- |
| `steer_intent` | `domain`, `kernel_constraints`, `alpha?`, `exclude_tags?` | One directive, hard-capped at 35 tokens |
| `commit_output` | `hash_id`, `used_patterns` | Local anti-repeat acknowledgement |
| `diversity_telemetry` | none | Same/near/far counts and a normalized entropy score |

The directive has one job: tell the model what must survive, what must not appear, and which cross-domain lens to use.

| Field | Meaning |
| :--- | :--- |
| `KEEP` | Invariant functional constraints. They must survive the steering. |
| `BAN` | Stock patterns the result must avoid. |
| `ANCHOR` | Primary concept plus a secondary concept from another domain. |
| `HASH` | 64-bit SimHash used by `commit_output` and the novelty check. |

## Why not raise temperature?

Temperature changes how randomly the model samples. It has no idea which directions are the domain's clichés, so a high value produces more variance and more broken structure: code that stops compiling, music that loses its pulse, layouts that stop reading.

KADRAN-H removes named stock patterns from a fixed concept space and keeps the task's kernel fixed. The model still writes the answer; it starts from a different lens instead of a noisier one.

## How it works

```mermaid
flowchart LR
  A[Task intent] --> B[Kernel / orbit split]
  B --> C[Gram-Schmidt rejection]
  C --> D[Sobol anchor pair]
  D --> E[SO 64 geodesic rotation]
  E --> F[64-bit SimHash]
  F --> G[Directive]
```

<details>
<summary>Math and implementation notes</summary>

1. The intent is split into a protected kernel and a stylistic orbit: `v = v_K + v_perp`.
2. Active clichés and committed patterns are orthonormalized with modified Gram-Schmidt. The orbit is projected out of their span: `v_perp = v - Σ <v, c_i> c_i`.
3. A primary anchor comes from the selected domain. A secondary anchor comes from another domain. The pair is chosen with a Sobol-ranked permutation, so repeated calls walk the lattice instead of clustering on random picks.
4. The orbit is rotated by `theta = alpha * PI / 2` toward the anchor while the kernel is copied through unchanged. The orbit norm is conserved:
   `v_star = v_K + ||v_perp|| * (cos(theta) * u_orbit + sin(theta) * u_anchor)`.
5. A 64-bit SimHash (`sign(Rx)`) fingerprints the result. Novelty is Hamming distance, computed with XOR and popcount. History never leaves the machine.
6. If an anchor collapses into the banned subspace, a deterministic Halton point in R^64 is used as the escape vector.

The concept vectors are deterministic hashed bag-of-words projections, not a neural encoder. See [Limitations](#limitations).

</details>

<details>
<summary>Generated samples for all five domains</summary>

```text
coding_architecture: [HQMS α=0.95 | KEEP:O(1) rate limiter,thread-safe | BAN:Redis Cache,Token Bucket,LRU Map | ANCHOR:Immune Memory × Korean Pansori | HASH:fef5b72738b98dfd]
music_composition: [HQMS α=0.90 | KEEP:80 BPM,warm bass,uninterrupted flow | BAN:Four Chord Pop,Lo-Fi Rain Beat,4/4 Jazz Piano | ANCHOR:Carnatic Ragam × Ottoman Calligraphy | HASH:0140aae1abc53362]
visual_design: [HQMS α=0.90 | KEEP:high trust,clear CTA,readable | BAN:Purple Blue Gradient,Glassmorphism Cards,3D Hero Blob | ANCHOR:Transit Wayfinding × Border Crossing File | HASH:e368816e5733c3ab]
creative_writing: [HQMS α=0.85 | KEEP:first person,unreliable memory,short sentences | BAN:Hero's Journey,Chosen One,Dystopian YA | ANCHOR:Oral Epic Formula × Akerman Domestic | HASH:f2001946581181c0]
cultural_discovery: [HQMS α=0.90 | KEEP:deep loneliness,inner observation | BAN:The Prestige,Her,Blade Runner 2049 | ANCHOR:Calvino Cosmicomics × Kolmogorov Compression | HASH:04ecac48c5f68a02]
```

</details>

## Domains

Each pack has 36 anchors and 16 mode ideals. The 180 anchors span computer science, physics, architecture, music theory, philosophy, biology, and literature. A primary anchor from the chosen domain is paired with a secondary anchor from another domain, giving 5,184 ordered cross-domain pairs per domain.

| Domain | Example banned average | Example anchors |
| :--- | :--- | :--- |
| `coding_architecture` | Redis Cache, Token Bucket | Immune Memory, CRDT Semilattice |
| `music_composition` | Four Chord Pop, Lo-Fi Rain Beat | Gamelan Polyrhythm, Carnatic Ragam |
| `visual_design` | Purple Blue Gradient, Glassmorphism Cards | Risograph Overprint, Transit Wayfinding |
| `creative_writing` | Hero's Journey, Dystopian YA | Oulipo Lipogram, Oral Epic Formula |
| `cultural_discovery` | The Prestige, Blade Runner 2049 | Akerman Domestic, Slow Cinema |

`src/lattice/domains.json` is the contribution surface. Adding anchors or mode ideals requires no code: keep labels short, add the concept to the relevant array, and run `npm test`.

## Privacy and state

The server speaks stdio and makes no outbound requests. It does not store prompts, source code, or generated text. `~/.kadran-h/history.json` holds 64-bit hashes, anchor labels, domain keys, same/near/far counters, and the pattern tags passed to `commit_output`. Set `KADRAN_H_HOME` to relocate it. Deleting the file resets the anti-repeat memory.

## Performance

Measured on Node v24.19.0, Windows 11, Intel i7-14650HX. Reproduce with `npm run bench`.

| Workload | Calls | p50 | p95 | Max | Tokens |
| :--- | ---: | ---: | ---: | ---: | ---: |
| In-memory steering | 1,000 | 0.592 ms | 0.903 ms | 1.329 ms | 18–22 |
| File-backed steering | 200 | 1.279 ms | 1.689 ms | 1.970 ms | 18–21 |

The file-backed row includes the atomic write to `~/.kadran-h/history.json`. The hard token cap is 35; the benchmark workload stays below it. No remote API, no model call, no neural embedding model.

## Verification

`npm test` runs 12 tests: quotient rejection, kernel and orbit-norm preservation, Sobol permutations, SimHash determinism, 30 unique anchors and hashes in under 100 ms, 35-token caps across every domain, persistent telemetry, and aliases.

```text
$ npm test
Test Files  1 passed (1)
Tests       12 passed (12)
```

CI runs typecheck, tests, build, and a real stdio MCP handshake (`npm run smoke`) on Node 20, 22, and 24.

## Limitations

- Hashed bag-of-words vectors are deterministic and local. They do not capture semantics the way a trained embedding model does. The anchor is a lens, not a guarantee of quality.
- Anti-repeat memory keeps the last 128 anchors and 512 committed hashes. Old pairs can return after that window.
- One local JSON store, one process. There is no multi-process locking, HTTP transport, team sync, or ONNX bridge.
- KADRAN-H does not write the answer and does not verify factual correctness. The model still has to do the work.

## Development

```bash
npm run typecheck
npm test
npm run build
npm run smoke
npm run bench
npm run samples
npm run inspector
```

Set `KADRAN_H_HOME` to move the store. The default is `~/.kadran-h`. Delete `history.json` inside that directory to reset the anti-repeat memory.

## Contributing

The easiest contribution is a new anchor or mode ideal in `src/lattice/domains.json`. Keep labels to 2–4 words, add the concept to one domain, then run:

```bash
npm run typecheck
npm test
```

For code changes, include a test that fails without the change. Open a pull request against `main`; CI runs on Node 20, 22, and 24.

<details>
<summary>Troubleshooting</summary>

- `Cannot find module .../dist/mcp/server.js`: run `npm run build` after `npm ci`.
- Windows MCP config cannot start the server: use forward slashes in `args` or escape each backslash in JSON.
- Manual tool inspection: `npx @modelcontextprotocol/inspector node dist/mcp/server.js`.
- `alpha` outside 0..1: the MCP input schema rejects it; pass a value between 0 and 1.
- Reset memory: delete `~/.kadran-h/history.json`, or the file under `KADRAN_H_HOME`.

</details>

## License

MIT. See [LICENSE](LICENSE).

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct role in a clear workflow: diversity_telemetry reads memory statistics, steer_intent computes a steering directive, and commit_output writes results back to memory. There is little risk of confusing read, compute, and commit operations.

Naming Consistency4/5

steer_intent and commit_output follow a clear verb_noun pattern, while diversity_telemetry is noun_noun but still readable and domain-specific. The deviation is minor and does not impair understanding.

Tool Count5/5

Three tools are tightly scoped to the anti-repeat memory workflow, with each tool earning its place. The surface is small but appropriate for the narrow purpose.

Completeness4/5

The read-compute-commit lifecycle is covered, which is the core workflow. Minor gaps exist around explicitly resetting or listing stored memory entries, but agents can likely work around these.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues