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:[email protected]       # pinned
pi -e npm:pi-qmd-ledger                  # try without installing

Or from git (SSH):

pi install git:[email protected]:kylebrodeur/pi-qmd-ledger
pi install git:[email protected]:kylebrodeur/[email protected]

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).