Mermaid Context Kit

Mermaid Context Kit is an npm package for documenting and retrieving source-grounded RAG architecture with compact YAML indexes and derived Mermaid diagrams.

Its primary skill, mermaid-rag, helps coding agents maintain an evidence-backed map of ingestion, parsing, chunking, embedding, indexing, retrieval, reranking, generation, citation, memory, and evaluation components. The package also includes mermaid-mem as a companion skill for shared project context and private session memory.

Mermaid Rag

Mermaid Rag treats YAML as the authoritative architecture index and Mermaid as its derived topology view. It connects architecture entities to their current source and configuration evidence so agents can retrieve relevant files without loading an entire repository.

flowchart LR
    query["Task or architecture query"] --> index["YAML RAG index"]
    index --> topology["Components and flows"]
    topology --> files["Relevant source files"]
    files --> evidence["Verified evidence"]
    evidence --> index
    index --> diagram["Derived Mermaid topology"]

The skill supports:

• Evidence-backed RAG components across 12 approved pipeline stages.
• Verified, provisional, and stale architecture states.
• Typed and validated component relationships.
• Top-level and stage-sharded YAML indexes.
• Exact YAML-to-Mermaid topology validation.
• Architecture-first, low-context source retrieval.
• Git-based recency scoring and deterministic fallback behavior.

Start Mermaid Rag

After installation, invoke the skill explicitly with $mermaid-rag, or use one of its trigger phrases:

• initiate mermaid rag
• start mermaid rag
• updated mermaid rag

For example:

Start mermaid rag and document this project's ingestion and retrieval architecture.

The skill maintains these project artifacts:

docs/ai-context/
├── rag-index.yaml
├── rag-architecture.md
└── rag/
    └── <optional-stage-shards>.yaml

It inspects only named or directly implicated RAG paths, records evidence fingerprints, updates YAML first, derives the managed Mermaid region, and then validates the complete top-level-plus-shard architecture.

Architecture-First Retrieval

The bundled retrieval helper ranks architecture relevance before recency:

1. Match exact component, flow, or stage terms.
2. Expand architecture neighbors to depth 1 by default.
3. Use Git last-commit recency bands as tie-breakers.
4. Include only files with confidence >= 0.35.
5. Use recency-weighted lexical fallback when architecture matching is empty.

The fixed confidence signals are:

| Signal | Weight | | --- | ---: | | Exact architecture match | 0.60 | | Depth-1 adjacency | 0.25 | | Git recency band | 0.15 |

Run a retrieval query with:

python3 mermaid-rag/scripts/retrieve-context.py \
  --root . \
  --index docs/ai-context/rag-index.yaml \
  --query "retrieval reranking flow"

Results stay compact:

src/retrieval.py | score=0.75 | matched=hybrid-retriever,query-flow

When no architecture or fallback result reaches the confidence threshold, the helper returns a compact diagnostic with query-refinement hints. Use --max-depth 2 only when deeper graph expansion is explicitly required.

Validate RAG Architecture

Validate a project only after Mermaid Rag has created:

docs/ai-context/rag-index.yaml
docs/ai-context/rag-architecture.md

From PowerShell, use a single-line command:

python mermaid-rag/scripts/validate-rag.py --root . --index docs/ai-context/rag-index.yaml --diagram docs/ai-context/rag-architecture.md

From Bash or another POSIX shell:

python3 mermaid-rag/scripts/validate-rag.py \
  --root . \
  --index docs/ai-context/rag-index.yaml \
  --diagram docs/ai-context/rag-architecture.md

Do not substitute tests/skills/mermaid_rag/fixture/config/rag.yaml or tests/skills/mermaid_rag/baseline-results.md. They are application fixture configuration and test documentation, not a RAG architecture index and managed diagram.

Successful validation prints:

PASS structural-validation

If validation reports that PyYAML is unavailable, install it into the same Python interpreter:

python -m pip install PyYAML

To verify Mermaid Rag inside this package repository before the project artifacts exist, run the Python test suites instead:

python -m unittest -v tests.skills.mermaid_rag.test_validate_rag tests.skills.mermaid_rag.test_skill_contract tests.skills.mermaid_rag.test_retrieve_context

The suite ends with OK when successful.

Validation checks schema shape, approved stages and transitions, evidence-path containment, fingerprints, shard limits, component and edge uniqueness, and exact agreement between the YAML union and managed Mermaid topology.

Installation

Node.js 18 or newer is required for the installer.

# Install both skills into the current project
npx mermaid-context-kit@latest install

# Install both skills for the current user
npx mermaid-context-kit@latest install --global

# Install both skills for Hermes
npx mermaid-context-kit@latest install --platform hermes

The installer upgrades recognized mermaid-rag and mermaid-mem installations atomically. It refuses to overwrite unrelated skill directories.

Manual Installation

Clone the repository:

git clone https://github.com/iammikz/mermaid-context-kit.git
cd mermaid-context-kit

For a Codex project installation:

mkdir -p /path/to/project/.agents/skills
cp -R mermaid-rag mermaid-mem /path/to/project/.agents/skills/

For a personal Codex installation:

mkdir -p "$HOME/.agents/skills"
cp -R mermaid-rag mermaid-mem "$HOME/.agents/skills/"

Codex discovers skills under .agents/skills and follows symlinked skill directories.

For Hermes, add the skill directories to ~/.hermes/config.yaml:

skills:
  external_dirs:
    - /absolute/path/to/mermaid-context-kit/mermaid-rag
    - /absolute/path/to/mermaid-context-kit/mermaid-mem

Alternatively, copy both directories into ~/.hermes/skills/.

Requirements

• Git
• Python 3.10 or newer
• PyYAML for YAML loading and full validation
• Optional: Mermaid CLI (mmdc) for visual-render validation
• Node.js 18 or newer when using the npm installer

Mermaid Rag Package Structure

mermaid-rag/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── assets/
│   └── rag-templates/
│       ├── rag-index.yaml
│       └── rag-architecture.md
├── references/
│   └── rag-schema.md
└── scripts/
    ├── retrieve-context.py
    └── validate-rag.py

Keep SKILL.md concise. Detailed schema, stage, relationship, sharding, and validation contracts belong in references/rag-schema.md; reusable starter artifacts belong in assets/rag-templates/.

Mermaid Mem Companion

mermaid-mem provides compact context routing outside the RAG architecture index:

• Shared project memory lives in docs/ai-context/.
• Private session memory lives in .ai-memory-local/.
• Durable verified facts belong in shared memory.
• Hypotheses, blockers, and unfinished work belong in private memory.

Use Mermaid Mem when the task is about repository-wide context or session continuity. Use Mermaid Rag when the task concerns RAG components, stages, evidence, source retrieval, or pipeline topology.

Trigger Mermaid Mem with initialize mermaid mem, start mermaid mem, or update mermaid mem.

Development and Testing

Install PyYAML in the development environment:

python3 -m pip install PyYAML

Run the package tests:

npm test

Run the Mermaid Rag test suites:

python3 -m unittest -v \
  tests.skills.mermaid_rag.test_validate_rag \
  tests.skills.mermaid_rag.test_skill_contract \
  tests.skills.mermaid_rag.test_retrieve_context

Check the helper interfaces:

python3 mermaid-rag/scripts/validate-rag.py --help
python3 mermaid-rag/scripts/retrieve-context.py --help

If OpenAI's skill-creator is available, validate the packaged skill shape:

python3 /path/to/skill-creator/scripts/quick_validate.py mermaid-rag

Safety

• Treat current source code, configuration, tests, and authoritative project documentation as higher priority than generated architecture artifacts.
• Never mark unknown, inferred, or conflicting architecture facts as verified.
• Review generated YAML and Mermaid changes before sharing them.
• Keep private Mermaid Mem artifacts excluded from version control.
• Never place secrets, transcripts, personal data, or source-file contents in generated context artifacts.

Documentation

• OpenAI: Build skills
• Hermes Agent: Skills System
• Agent Skills specification