pi-qmd-ledger

Universal append-only JSONL ledger with hybrid semantic search (qmd) and dynamic context injection for pi.

Features

• Universal — user-defined schema per ledger. Works for research, decisions, requirements, experiments, docs-anything.

• Append-only — immutable history with configurable dedup.

• Tiered HITL — strict (confirm each), gated (queue for review), autopilot (auto-append).

• Semantic search — fuzzy retrieval via qmd across raw documents.

• Context injection — regex triggers auto-inject ledger entries into prompts.

• Self-adapting — runtime config changes, schema evolution, multiple named ledgers.

• Extension Compatibility — Integrates with other pi extensions (e.g., pi-context) for enhanced features, dynamically loading capabilities when extensions are present.

Architecture

┌─────────────────────────────────────────┐
│  User prompt                             │
│  e.g. "draft login"                      │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Injector regex match                    │
│  → matches "draft\s+(\S+)"              │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  query main.jsonl where tag="login"   │
│  + inject artifact.md                   │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Appended to system prompt               │
│  → LLM now has pre-fetched context       │
└─────────────────────────────────────────┘

For more details on extension integration, see topics/EXTENSIONS.md.

Quick Start

Prerequisites

• qmd binary on PATH (prebuilt or via cargo install --git https://github.com/kylebrodeur/qmd --branch patch-0.3.2 qmd-cli)
• Node.js 20+ (matches engines in package.json)

1. Install with pi

pi install npm:pi-qmd-ledger              # latest
pi install npm:pi-qmd-ledger@0.2.4       # pinned
pi -e npm:pi-qmd-ledger                  # try without installing

Or from git (SSH):

pi install git:git@github.com:kylebrodeur/pi-qmd-ledger
pi install git:git@github.com:kylebrodeur/pi-qmd-ledger@v0.1.1

2. Verify the install

/pi list
/qmd-validate

You should see pi-qmd-ledger in the package list and a green health check for qmd, config, and ledgers.

3. Scaffold your ledger

Inside any project:

/qmd-init
/qmd-validate

This creates pi-qmd-ledger.config.json and empty ledger files.

4. Index your documents

Before qmd_search works, you need to build the search index:

# Add a collection (run from the directory containing your .md files)
qmd collection add ./docs --name my-docs

# Build the full-text (BM25) and vector indexes
/qmd-index

# Check status
qmd_status

5. Adapt the config

Edit pi-qmd-ledger.config.json to match your domain. See Config Reference.

Install from npm (classic)

If you are not using pi's package manager:

npm install pi-qmd-ledger
# or
pnpm add pi-qmd-ledger
# or
yarn add pi-qmd-ledger

Then register in your project's package.json:

{
  "pi": {
    "extensions": ["./node_modules/pi-qmd-ledger/dist/index.js"]
  }
}

Installing from source

git clone https://github.com/kylebrodeur/pi-qmd-ledger.git
cd pi-qmd-ledger
pnpm install && pnpm build

Example domains

Research project

{
  "ledgers": {
    "findings": {
      "path": "research/findings.jsonl",
      "schema": ["id", "paper", "claim", "evidence", "confidence", "tag"],
      "dedupField": "claim"
    }
  },
  "injectors": [
    {
      "name": "lit-review",
      "regex": "review\\s+(\\S+)",
      "ledger": "findings",
      "filterField": "tag",
      "artifactPath": "research/synthesis.md"
    }
  ]
}

Decision log

{
  "ledgers": {
    "decisions": {
      "path": "decisions/log.jsonl",
      "schema": [
        "id",
        "date",
        "context",
        "decision",
        "rationale",
        "status",
        "owner"
      ],
      "dedupField": "decision"
    }
  },
  "injectors": [
    {
      "name": "decide",
      "regex": "decide\\s+(\\S+)",
      "ledger": "decisions",
      "filterField": "context"
    }
  ]
}

Tools

Tool	Purpose
qmd_search	Fuzzy semantic search via qmd
qmd_status	Show qmd collections, indexed docs, and embedding state
query_ledger	Deterministic JSONL search by ledger name
append_ledger	Append with strict/gated/autopilot modes
configure_ledger	Read or update config at runtime
describe_ledger	Introspect schema, count, and sample entries
ledger_stats	Dashboard: counts, sizes, qmd version
ledger_export	Export to JSON, CSV, or Markdown

Commands

Command	Purpose
/qmd-init	Scaffold config + ledgers + artifact templates
/qmd-validate	Health check everything
/qmd-index [--no-embed]	Re-index all collections (BM25 + embeddings)
/qmd-approve [target]	Batch-review pending entries
/qmd-list-extensions	List available and enabled extension integrations
/qmd-extension-status	Show detailed extension compatibility status
/qmd-enable-pi-context	Enable or disable pi-context integration

Documentation

Doc	Description
Skill	What pi auto-loads about this extension
Config Reference	Full config schema, env overrides, resolution order
Tool Reference	All 7 tools: parameters, behavior, return types
Troubleshooting	Common issues and fixes

Contributing

See CONTRIBUTING.md for dev setup, testing, and commit conventions.

License

MIT — see LICENSE (or package.json).