Skip to content

weby-homelab/power-framework

BranchesTags

Repository files navigation

ENG | UKR

P.O.W.E.R. — AI-Native Toolkit for Second Brain

Validate, index, search, and manage your knowledge base from the command line — or let AI agents do it through MCP. Built for knowledge workers who want machine-readable notes, automated quality checks, and token-efficient AI access to their Second Brain.

CI Coverage Release Python 3.10+ License: GPL v3 CodeQL Docs

About P.O.W.E.R. - Hybrid Knowledge Management Framework

P.O.W.E.R. is a hybrid system built to bridge the gap between human workflows, automated scripts, and LLM-based autonomous agents. The name is an acronym representing its core components: P.A.R.A., OKF, Wiki, and Execution Rules. It integrates these distinct architectural frameworks to construct a coherent, self-validating, and token-efficient Second Brain.

Why P.O.W.E.R.?

Unlike generic knowledge management tools, P.O.W.E.R. is designed from the ground up for AI-first knowledge management:

  • AI-native metadata — Pydantic v2 schemas enforce strict OKF frontmatter, so every note is machine-readable; includes governance fields (owner, status, expiry) and Graph RAG links (related)
  • Token-efficient indexing — hierarchical index.md + per-folder _index.md cuts AI agent context usage by ~75%
  • Knowledge Graph — related field connects notes across the vault; visualized in sub-indexes for Graph RAG workflows
  • Freshness Monitoring — linter detects stale/expired notes based on expiry metadata field
  • Agent Auto-Ingest — synthesize_session MCP tool lets agents autonomously create permanent knowledge artifacts with governance + graph links + full catalog maintenance
  • MCP-native — expose all 12 tools to any MCP-compatible AI client (Claude, OpenCode, Cursor) with zero glue code, powered by FastMCP 3.x
  • Production-grade — 377 tests, 73%+ coverage (CI fail-under=70), CodeQL scanning, Automated GitHub Releases

Quick Start

pip install git+https://github.com/weby-homelab/power-framework.git@v2.1.2

power init ~/my-vault          # Create vault structure
power lint ~/my-vault          # Check for broken links & missing metadata
power index ~/my-vault         # Generate catalog index.md
power heal ~/my-vault          # Auto-fix missing/invalid frontmatter
power markdown-check ~/my-vault  # Check markdown quality issues

Development Install (editable + easy update)

For a permanent, always-updatable CLI on your workstation (WS), install in editable mode from a local clone. This binds power to the repo so code changes take effect immediately — no reinstall needed.

# 1. Clone once
git clone https://github.com/weby-homelab/power-framework.git /tmp/power-framework
cd /tmp/power-framework

# 2. Editable install into user-site (survives reboots, no venv required)
pip install --user --break-system-packages -e ".[dev]"

# 3. Verify — `power` is now on PATH (via ~/.local/bin)
power --version

Update to the latest code anytime with:

cd /tmp/power-framework && git pull origin main && power --version
# If pyproject.toml changed (new deps/version), reinstall:
pip install --user --break-system-packages -e ".[dev]"

💡 One-liner updater. Save this as /root/.local/bin/power-update and chmod +x it, then just run power-update to pull + reinstall automatically:

#!/usr/bin/env bash
set -euo pipefail
REPO="/tmp/power-framework"
cd "$REPO"
git fetch origin main && git reset --hard origin/main
if git diff --name-only HEAD@{1} HEAD | grep -q pyproject.toml; then
  pip install --user --break-system-packages -e ".[dev]" >/dev/null 2>&1
fi
power --version

What's Inside

Feature What it does
CLI power init, lint, index, ingest, search, rot, status, archive, cron, heal, markdown-check, suggest-related — 12 commands for full vault management
MCP Server Exposes lint_vault, generate_index, read_sub_index, ensure_sub_index, ingest_note, search_vault_tool, synthesize_session, rot_audit, archive_notes, suggest_related_tool, heal_frontmatter_tool, check_markdown_tool — 12 tools for AI agents
OKF Validation Pydantic v2 schemas enforce strict metadata on every note with governance (owner, status, expiry)
Knowledge Graph (Graph RAG) related field in OKF frontmatter supporting TypedRelation (path, relation, confidence) with BFS traversal and Mermaid diagram export (to_mermaid)
Freshness Monitoring Linter flags stale/expired notes by checking expiry dates, ensuring your vault stays current
Agent Auto-Ingest synthesize_session MCP tool — agents autonomously create permanent notes with governance + graph links + full index rebuild
ROT Audit Detects redundant, outdated, and trivial notes using dense embedding semantic deduplication and LLM fact contradiction checks
Auto-Archive Automatically archives stale notes to 04_Archive/ — power archive <path> with dry-run preview
Healer Auto-fixes missing/invalid frontmatter fields (title, description, type, timestamp) — power heal <path>
Markdown Checks Detects trailing whitespace, inconsistent list markers, header jumps, missing code language — power markdown-check <path>
Relation Suggestions Keyword & tag overlap analysis for Graph RAG enrichment — power suggest-related <path>
Cron Maintenance Runs lint + index + rot audit in one command — power cron <path>
Advanced Hybrid Search 5-mode search: FTS5 (BM25), Dense Vector Semantic, Hybrid (RRF fusion), Semantic, and Hybrid Reranked. Default backend Qwen3-Embedding-0.6B (1024d, ONNX, multilingual, recommended for UA↔EN vaults) or fastembed MiniLM-L12 (384d, light). Includes synonym & LLM query expansion and Contextual Retrieval chunking (SemanticChunker)
Cross-Encoder Reranker hybrid_reranked mode uses the multilingual Qwen3-Reranker-0.6B-ONNX (via qwen3-embed, no PyTorch). Fixes the old MiniLM reranker which degraded mix-lingual quality (MAR@5 −22%, ×8 latency). POWER_EMBED_PROVIDER=fastembed falls back to ms-marco-MiniLM-L-6-v2
Hierarchical Index index.md (navigation map) + per-folder _index.md (detailed catalogs) for token-efficient AI reading (~75-94% token savings)
CI/CD 377 tests, 73%+ coverage, CodeQL SAST, Automated GitHub Releases
Documentation Full mkdocs-material site with API reference and guides

Migration Report

Read the full technical report on the transition from flat to hierarchical indexing:

AI Agent Migration Guide

Step-by-step protocol for any AI agent (Claude, GPT, Gemini, OpenCode) to autonomously migrate an existing knowledge base into P.O.W.E.R. structure:

Who Is This For

  • Knowledge workers who want AI agents to understand and maintain their knowledge base
  • Developers building a structured Second Brain with machine-readable metadata
  • Teams that need consistent note formatting and automated quality checks

Commands

power init <path>              Create a new vault with P.A.R.A. folder structure
power lint <path>              Scan for broken links, missing metadata, orphans
power index <path>             Generate hierarchical index (index.md + _index.md files)
power search <path> <query>    Full-text search with relevance scoring
power ingest <path> [options]  Create a new note with validated OKF metadata
power rot <path>               ROT Audit — detect redundant, outdated, trivial notes
power status [path]            Show vault status dashboard (statistics & health metrics)
power heal <path>              Auto-heal missing/invalid frontmatter
power markdown-check <path>    Check markdown quality issues
power archive <path>           Auto-archive stale notes to 04_Archive/
power suggest-related <path>   Suggest cross-note relations for Graph RAG
power cron <path>              Run automated maintenance (lint + index + rot)

Ingest Examples

power ingest ~/my-vault --type Project --title "My App" --description "A new project"
power ingest ~/my-vault --type Resource --title "Docker Guide" --description "Docker best practices" --tags devops,docker --resource "https://docs.docker.com"

Search Examples

power search ~/my-vault "api authentication"
power search ~/my-vault "deployment guide" --max-results 5

MCP Server Setup

Connect P.O.W.E.R. to any MCP-compatible AI client (local stdio or Docker HTTP transport).

pip install git+https://github.com/weby-homelab/power-framework.git@v2.1.2

Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
    "mcpServers": {
        "power": {
            "command": "python3",
            "args": ["-m", "power_framework.mcp"],
            "env": {
                "POWER_VAULT_DIR": "/path/to/your/my-vault"
            }
        }
    }
}

OpenCode (~/.config/opencode/opencode.jsonc):

"mcp": {
  "power": {
    "type": "local",
    "command": ["python3", "-m", "power_framework.mcp"],
    "enabled": true
  }
}

Vault Structure

P.O.W.E.R. organizes your vault using the P.A.R.A. method with OKF metadata on every note:

~/my-vault
├── 00_Inbox/
│   └── _index.md        # Detailed sub-index for Inbox notes
├── 01_Projects/
│   └── _index.md        # Detailed sub-index for Projects
├── 02_Areas/
│   └── _index.md        # Detailed sub-index for Areas
├── 03_Resources/
│   └── _index.md        # Detailed sub-index for Resources
├── 04_Archive/
│   └── _index.md        # Detailed sub-index for Archive
├── 05_Templates/        # Note templates with OKF frontmatter
├── 06_Daily_Logs/
│   └── _index.md        # Detailed sub-index for Daily Logs
├── PROTOCOLS/           # System specs for AI agents
├── index.md             # Navigation map (links to sub-indexes)
└── log.md               # Append-only change log

Hierarchical Index Protocol

AI agents read the vault efficiently by following this pattern:

  1. Read index.md — identify the relevant category by note counts
  2. Call read_sub_index MCP tool — get detailed entries for that category
  3. Read specific notes — only when the sub-index indicates relevance
  4. NEVER glob all .md files — use sub-indexes as a map (~75% token savings)

Every note starts with validated YAML frontmatter. Core fields + optional governance and graph links:

---
type: Project
title: "My App"
description: "A new project with clear goals"
tags: [active, dev]
timestamp: 2026-07-02T19:00:00
owner: "team-alpha" # optional: governance — responsible owner
status: active # optional: active | review | archived
expiry: 2026-12-31 # optional: freshness management
related:
    - path: 01_Projects/Other.md
      relation: depends_on # optional: relation type
      confidence: 1.0 # optional: confidence score
---

Architecture Details

P.O.W.E.R. Methodology — click to expand

The framework combines four complementary methodologies:

  • P — P.A.R.A. (Projects, Areas, Resources, Archive) — Organizes files based on actionability into Projects, Areas, Resources, and Archives. P.O.W.E.R. adopts this directory structure to dictate the lifecycle of notes. Information moves organically from raw inbox captures to active project execution, long-term reference areas, and eventual archives.
  • O — OKF Overlay (Open Knowledge Format) — Imposes a strict schema layer over standard Markdown files. Built on Pydantic v2 schemas, OKF requires every note to be explicitly typed and validated (containing required frontmatter attributes such as title, description, tags, and timestamps). This turns unstructured markdown folders into a predictable, queryable, and machine-readable local database.
  • W — LLM-Wiki (A. Karpathy's philosophy) — Transforms the knowledge base into a hierarchical, AI-readable catalog. By generating top-level index.md maps and folder-level _index.md sub-catalogs, it provides token-efficient navigation that slashes AI agent context usage by 75% to 94%.
  • E.R. — Execution Rules — Integrates operational rules and guidelines specifically formatted for AI agents (like RULES.md, PROMPTS.md, and system-level guidelines), enforcing safe, non-destructive editing boundaries and dictating how human and AI actors interact with the system. GPG-signed commits, PR-only workflow, cron-based sync, branch cleanup.

Visual Framework Diagram

flowchart TD
    %% Modern 2026 Styling
    classDef human fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#fff,rx:8
    classDef data fill:#0ea5e9,stroke:#0369a1,stroke-width:2px,color:#fff,rx:8
    classDef wiki fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff,rx:8
    classDef rag fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff,rx:8
    classDef agent fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#fff,rx:8
    classDef security fill:#ef4444,stroke:#b91c1c,stroke-width:2px,color:#fff,rx:8

    subgraph Human ["👤 Human (Markdown UI)"]
        PARA[["📁 P.A.R.A. Directory Structure"]]:::human
    end

    subgraph OKF ["📄 OKF Overlay (Metadata & GraphRAG Schema)"]
        YAML[/"📝 YAML Frontmatter with Typed Relations"\]:::data
    end

    subgraph RAG ["🔍 RAG & GraphRAG Pipeline"]
        Chunker["✂️ Semantic Chunker (Anthropic Contextual)"]:::rag
        Embeddings["🧠 Dense Embeddings<br/>(Qwen3-0.6B default / MiniLM)"]:::rag
        SQLite[("🗄️ SQLite (FTS5 + chunk_embeddings)")]:::rag
        Expander["🔄 Query Expander (Synonyms / LLM)"]:::rag
        Reranker["🎯 Cross-Encoder Reranker (Qwen3-0.6B)"]:::rag
        KG["🕸️ Knowledge Graph (BFS / Mermaid Graph)"]:::rag
    end

    subgraph Wiki ["📖 LLM-Wiki (Hierarchical Catalog)"]
        IndexMD[("🗂️ index.md (Navigation Map)")]:::wiki
        SubIndex[("📂 _index.md (Per-Folder Details)")]:::wiki
        LogMD[("📜 log.md (Change Log)")]:::wiki
    end

    subgraph AI ["🤖 AI Agent (FastMCP 3.x)"]
        Tools[["🔌 12 Async MCP Tools (stdio/HTTP)"]]:::agent
        Search[["🔍 Hybrid / Reranked Search"]]:::agent
        ROT{{"🛠️ ROT & Contradiction Audit (Semantic/LLM)"}}:::agent
    end

    subgraph ER ["🔐 Execution Rules"]
        GPG(("🔑 GPG-Signed Commits")):::security
        PR(("🛡️ PR-Only Workflow")):::security
        Sync(("⏱️ Cron Auto-Sync")):::security
    end

    %% Data Flow
    Human -- "Writes Notes" --> PARA
    PARA -- "Enforces OKF" --> YAML
    YAML -- "Parsed by" --> Chunker

    %% RAG Pipeline
    Chunker -- "Contextual Chunks" --> Embeddings
    Embeddings -- "Stores Vectors" --> SQLite

    %% Search Pipeline
    Tools -- "Issues Query" --> Expander
    Expander -- "Multi-Queries" --> SQLite
    SQLite -- "FTS5 + Vector Candidates" --> Reranker
    Reranker -- "Top Ranked Results" --> Search

    %% GraphRAG Pipeline
    YAML -- "Defines Edges" --> KG
    KG -- "Renders Subgraphs" --> Tools

    %% Wiki Operations
    Tools -- "Auto-Ingests & Indexes" --> IndexMD
    Tools -- "Updates" --> SubIndex
    Tools -- "Appends Logs" --> LogMD

    %% ROT Audit
    Tools -- "Runs Audit" --> ROT
    ROT -- "Deduplicates" --> Embeddings
    ROT -- "Checks Conflicts" --> SQLite

    %% Sync & Security
    IndexMD -. "Synced via" .-> Sync
    SubIndex -. "Synced via" .-> Sync
    LogMD -. "Synced via" .-> Sync
    Sync -- "Triggers" --> GPG
    GPG -- "Enforces" --> PR
Loading

Core Library (src/power_framework/)

Module Purpose
core/models.py Pydantic v2 schemas for OKF metadata validation
core/parser.py Safe YAML frontmatter parsing (PyYAML-based)
core/indexer.py Vault scanning and hierarchical index generation
core/linter.py Health checks: broken links, missing metadata, orphans, stale/expired notes
core/searcher.py Full-text search with relevance scoring (FTS5/Vector/Hybrid/Reranked); WAL mode + busy_timeout for parallel access
core/embeddings.py Pluggable dense embedding manager: Qwen3-0.6B (default, 1024d) / MiniLM-L12-v2 (384d, light) via POWER_EMBED_PROVIDER, ONNX Runtime, lazy init, adaptive batch halving on OOM
core/reranker.py Cross-Encoder reranker: Qwen3-Reranker-0.6B-ONNX (default when provider=qwen3, no PyTorch) or ms-marco-MiniLM-L-6-v2 fallback
core/metrics/udcg.py UDCG retrieval metric (EACL 2026) — utility-aware replacement for MRR/nDCG for LLM RAG evaluation
core/query_expansion.py Synonym map (EN/UK) & OpenRouter Multi-Query expansion
core/chunker.py Semantic & contextual note splitter (Anthropic Contextual Retrieval)
core/healer.py Auto-fix missing/invalid frontmatter fields
core/relations.py KnowledgeGraph builder, BFS traversal, and Mermaid exporter
core/rot_scoring.py A2 scoring: semantic content dedup, freshness, contradiction checks
core/markdown_checks.py Markdown quality checks: trailing whitespace, list markers, header jumps
core/constants.py Centralized exclusion lists and system constants
core/utils.py Path traversal protection, atomic writes, backups, rate limiter
core/cli.py Command-line interface (12 commands via argparse)
mcp/power_server.py FastMCP 3.x server with 12 async tools + HTTP transport + /health

All components share power_framework.core as the single source of truth.

Development

git clone https://github.com/weby-homelab/power-framework.git
cd power-framework
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (377 tests, 73%+ coverage)
pytest tests/ -v

# Lint & format
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/power_framework/

Test Reports & Benchmarks

For detailed analysis and benchmarks of the P.O.W.E.R. framework:

Low-RAM Deployment (8–12 GB)

power sync builds dense embeddings for the whole vault. To stay safely under RAM limits on small hosts, v2.2.0 batches embeddings and degrades gracefully instead of crashing. Key knobs (see OOM_RECOVERY_PROTOCOL.md):

export POWER_EMBED_PROVIDER=qwen3            # default Qwen3-Embedding-0.6B (1024d, ~2.3 GB arena)
export POWER_EMBED_NUM_THREADS=2             # cap CPU threads on low-core boxes
export POWER_EMBED_BATCH_SIZE=8              # peak RAM bound; halves automatically on pressure
# export POWER_SYNC_VMEM_LIMIT_MB=6144       # opt-in hard backstop (0 = disabled; recommended on large hosts)

The default backend (v2.2.3+) is Qwen3-Embedding-0.6B-ONNX (1024d, ONNX Runtime, no PyTorch) which gives materially better cross-lingual quality than the old MiniLM-L12 (UA↔EN MAR@5 0.208 → ~0.35+). It allocates a ~2.3 GB ONNXRuntime arena per matmul node on CPU. On tight 8 GB hosts fall back to POWER_EMBED_PROVIDER=fastembed (MiniLM-L12, 384d) or raise POWER_SYNC_VMEM_LIMIT_MB.

⚠️ POWER_EMBED_NUM_THREADS is mandatory on big hosts. fastembed's parallel=0 spawns one model subprocess per CPU core. On a 20-core box that loaded 20 copies of the model → ~32 GB RSS. POWER now caps this to POWER_EMBED_NUM_THREADS (default 2, peak ~700 MB). Never raise it above what your RAM allows (cores × ~1.5 GB).

License

GPLv3 — Built in Ukraine ⚡

Built in Ukraine under air raid sirens & blackouts ⚡
© 2026 Weby Homelab

About

Validate, index, search, and manage your knowledge base from the command line — or let AI agents do it through MCP. Built for knowledge workers who want machine-readable notes, automated quality checks, and token-efficient AI access to their Second Brain

weby-homelab.github.io/power-framework/

Topics

python mcp self-hosted para obsidian homelab knowledge-management ai-agents second-brain okf llm-wiki execution-rules

Resources

Readme

License

GPL-3.0 license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

11 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 27

v2.2.3 — Qwen3 default embedding + UDCG metric Latest
Jul 19, 2026
+ 26 releases

Packages

 
 
 

Contributors

Languages