mdbind 0.1.12

MdBind — Structured memory in plain Markdown

MdBind

Structured memory in plain Markdown.

Transform your Markdown files into a navigable knowledge graph —
without databases, embeddings, or proprietary formats.

---

# Install
pip install mdbind

# Validate your docs folder
mdb validate --root docs/

# Get a section by URI
mdb get docs/intro.md#intro --json

---

What is MdBind?

MdBind turns Markdown files into a directed knowledge graph where every section is an addressable node with stable identity, metadata, and explicit relationships.

Your files stay plain text, Git-friendly, and human-readable — but gain:

• Graph traversal and dependency resolution
• Stable URIs that survive reorganization
• Structured metadata queries
• AI-oriented context retrieval with bounded token consumption

---

Why not embeddings?

Approach	Inspectable	Versionable	Deterministic	Human-readable
Vector databases	✗	✗	✗	✗
Proprietary stores	✗	partial	partial	✗
MdBind	✓	✓	✓	✓

Every node, every edge, every relationship is visible in the source file. What an agent reads, a human can audit.

---

Quick start

# 1. Clone and install
git clone <repo-url> && cd mdbind
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Point it at your docs
mdb validate --root docs/

# 3. Query the graph
mdb get docs/auth.md#auth --json

---

See it in action

# Navigate the dependency tree
$ mdb tree docs/auth.md#auth --root docs/

auth  [docs/auth.md]
├── jwt          [include]  docs/security.md#jwt
└── permissions  [ref]      docs/users.md#permissions

# Compose a unified document by expanding all @include directives
$ mdb compose docs/auth.md#auth --root docs/ --depth 2

# Find everything that depends on a node (reverse BFS)
$ mdb impact docs/auth.md#auth --root docs/ --json

# Boolean metadata query
$ mdb query "tag:api AND NOT status=obsolete" --root docs/ --json

# Bounded context for LLM consumption
$ mdb context-compose docs/auth.md#auth --root docs/ --depth 2 --token-limit 2000 --json

---

Syntax

Declaring a section

A section is a Markdown heading followed immediately by a YAML block with a section: field:

## Authentication

```yaml
section: auth
title: Authentication
type: domain
owner: security-team
tags: [auth, core]
```

Authentication is responsible for user identity.

[@include: JWT handling](security.md#jwt)

See also: [@ref: permissions model](users.md#permissions)

• The YAML block must be the first element after the heading
• section: is mandatory and must be unique per repository
• Any additional fields are preserved as queryable metadata

Optional schema validation

A section can opt into deterministic metadata validation by adding a schema field to its YAML block. The schema reference is local-first and resolved relative to the Markdown file that contains the section. A colocated schema/ directory is the recommended default; centralized schema directories can still be referenced with normal relative paths.

## Authentication

```yaml
section: auth
schema: schema/domain.schema.json
status: active
owner:
  team: security
```

Schemas are JSON Schema documents. They may be stored as .json, or as YAML when the YAML file encodes the same JSON Schema object. Validation is per-section only: there is no global repository schema, and sections without schema keep the existing free-form metadata behavior.

Directives (graph edges)

[@include: label](path/to/file.md#section-id)   <!-- expands inline during compose -->
[@ref: label](path/to/file.md#section-id)        <!-- records dependency, no expansion -->

Directives are standard Markdown links — they render correctly in any Markdown viewer.

auth
├── jwt          [include]
└── permissions  [ref]

---

Commands

Quick reference

Command	Description
mdb get <URI>	Extract a section with full documentary fidelity
mdb tree <URI>	Visual dependency hierarchy
mdb compose <URI>	Materialize a unified document (expands @include)
mdb validate	Check integrity: broken refs, cycles, duplicate IDs, local section schemas
mdb context <URI>	Metadata + immediate 1-hop neighborhood
mdb metadata get/update/unset <URI>	Read or edit structured YAML metadata
mdb backlinks <URI>	All sections that reference this URI
mdb search <predicate>	Search sections by metadata
mdb impact <URI>	All nodes that depend on this URI (reverse BFS)
mdb neighbors <URI>	All nodes reachable within N hops
mdb explain <URI_A> <URI_B>	All directed paths between two nodes
mdb diff	Structural graph diff against a git reference
mdb query <expression>	Boolean metadata/structure query (AND, OR, NOT)
mdb context-compose <URI>	Bounded materialization for LLM consumption

All commands accept --json for machine-readable output.
All outputs are deterministic and JSON-serializable. All URIs are stable across sessions.

Selected examples

# Validate an entire repository
mdb validate --root docs/ --json

# Validate one Markdown file in isolation
mdb validate --file docs/auth.md --json

# Single-file mode skips ordinary broken-ref errors for refs/includes that
# point to other files; use --root when validating the full project graph.

# Validate section metadata against local per-section schemas
mdb validate --root . --json

# 1-hop neighborhood of a node
mdb context docs/auth.md#auth --root docs/ --json

# Read and edit structured YAML metadata without touching the Markdown body
mdb metadata get docs/auth.md#auth owner.name --json
mdb metadata update docs/auth.md#auth status '"review"' --json
mdb metadata update docs/auth.md#auth owner '{"name":"Alice","team":"security"}' --json
mdb metadata unset docs/auth.md#auth draft_notes --json

# Find all sections tagged api that are not obsolete
mdb query "tag:api AND NOT status=obsolete" --root docs/ --json

# Find backlog-like section IDs with a regex predicate
mdb query "section~=/^backlog\\.item\\.B-\\d{3}$/ AND NOT status=done" --root docs/ --json

# Bounded context for LLM — depth 2, max 2000 tokens
mdb context-compose docs/auth.md#auth --root docs/ --depth 2 --token-limit 2000 --json

# What changed structurally since the last commit?
mdb diff --root docs/ --since HEAD~1 --json

---

Philosophy

Five principles behind every design decision:

1. Markdown is the source of truth — no proprietary formats, no hidden state
2. Knowledge should be inspectable — every node, every edge, every relationship is visible in the source
3. Relationships should be explicit — @include and @ref are first-class graph primitives
4. Stable identifiers are better than headings — file.md#id survives reorganization
5. AI memory should remain human-readable — what an agent reads, a human can audit

---

Examples

See the examples/ directory for a complete working knowledge base demonstrating sections, directives, composition, and graph traversal.

---

Development

# Install in editable mode
pip install -e .

# Run the full test suite
python -m pytest

# Run a specific module
python -m pytest tests/test_cli_validate.py -v

241 tests, 0 failures.

---

License

Apache License, Version 2.0