Skip to content

weby-homelab/power-framework

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 Release Python 3.10+ License: GPL v3 CodeQL Docs OKF BundleDex

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 up to 95%
  • Knowledge Graphrelated 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-Ingestsynthesize_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 (Antigravity, OpenCode, Claude Code CLI, Gemini 2.0, DeepSeek-R1, Cursor) with zero glue code, powered by FastMCP 3.x
  • Stable 3.2.4 release — hermetic tests and security checks are tracked in CI; the P.O.W.E.R. 3.2.4 release records all completed gates.

Quick Start

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

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, sync, rot, status, archive, cron, heal, markdown-check, suggest-related, synthesize, rename — 15 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>
Retrieval modes FTS5 (BM25), local TF vector, Hybrid (RRF), Semantic and Reranked modes. The POWER 3.2 default requires a compatible dense index and fails with a power sync remediation message when assets are missing or incompatible. An explicitly allowed FTS downgrade is marked in the result contract. Quality and resource figures require versioned evidence before any release claim.
Cross-Encoder Reranker The default BGE reranker is an Apache-2.0 ONNX snapshot with SHA-256 checks. Local jinaai/jina-reranker-v2-base-multilingual is CC-BY-NC-4.0 and requires POWER_RERANKER=jina plus POWER_ALLOW_NONCOMMERCIAL_MODELS=1 for permitted non-commercial use.
Hierarchical Index index.md (navigation map) + per-folder _index.md (detailed catalogs) for token-efficient AI reading (~75-94% token savings)
Graph RAG v2 Phase 3 relation suggester: explicit OKF related links contribute a strong curated signal, fused with keyword/tag overlap into a weighted, bidirectional similarity graph with weighted BFS and degree/weight centrality (power suggest-related --v2). Confident predictions only, no fabricated links.
ColBERT Opt-In Reranker Phase 3 POWER_RERANKER=colbert enables late-interaction ColBERT reranking (requires ≥16 GB RAM, otherwise skipped); it is off by default. The canonical fallback is the license-clean BGE ONNX reranker; Jina is available only through its explicit non-commercial opt-in.
Synthesize Auto-Ingest Phase 3 power synthesize <path> CLI (mirrors the MCP synthesize_session tool) auto-classifies OKF metadata, writes atomically, regenerates the hierarchical index, appends to log.md, and runs the lint report — the Auto-Ingest Feedback Loop.
Search-quality metric status The former UDCG@5 value is a legacy normalized discounted lexical proxy, not EACL-2026 UDCG, and is diagnostic only. No release-quality claim is made until true UDCG has paper-backed reference vectors.
CI/CD Hermetic tests, CodeQL SAST, and automated GitHub Releases; release evidence is validated by the versioned benchmarks/power31 harness and pinned model manifest.
Documentation Full mkdocs-material site with API reference and guides

POWER 3.2 beta evidence status: historical feature-table figures, model comparisons, resource limits and benchmark recommendations are not current release evidence. The framework remains beta/research until the P0/P1 gates in the 3.1 remediation plan are closed with versioned artifacts.

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 (Antigravity, OpenCode, Claude Code CLI, Gemini 2.0, DeepSeek-R1, Devin) to autonomously migrate an existing knowledge base into P.O.W.E.R. structure:

🗂️ Methodology compatibility

P.O.W.E.R. can index, search, and validate notes in an existing vault regardless of its folder scheme, including P.A.R.A., C.O.D.E., GTD, Zettelkasten, LYT, Johnny.Decimal, and custom layouts. In 3.2.4, power init <path> creates the default P.A.R.A. scaffold only. Selectable templates and the --template option are planned; they are not CLI features yet.

For another layout, create or retain its folders, then use P.O.W.E.R. to ingest notes and run lint, index, and search. OKF metadata validation and the available search tools work independently of the folder names.

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@v3.2.4

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:

  • PP.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.
  • OOKF 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.
  • WLLM-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.

🧠 Second Brain vs P.O.W.E.R. Framework Relationship & Collaboration

Second Brain (Obsidian Vault) and P.O.W.E.R. Framework form an integrated Knowledge Management System where Second Brain is the passive data store, and P.O.W.E.R. Framework is the active AI engine.

graph TD
    A[🤖 AI Agents: Antigravity / OpenCode / Codex] <-->|MCP Protocol / Skills / CLI| B[⚡ P.O.W.E.R. Framework Engine]
    B <-->|1. Hybrid Search BM25 + BGE-M3 + Reranker| C[(🧠 Obsidian Second Brain Vault)]
    B <-->|2. OKF Frontmatter Linter & Healer| C
    B <-->|3. Indexer & Graph Builder| C
    B <-->|4. ROT Audit & Maintenance| C
Loading

1. Second Brain (Obsidian Vault) — Passive Memory Store

  • What it is: A file-system knowledge base (/root/geminicli/brain) composed of standard Markdown files (.md).
  • Structure:
    • P.A.R.A. directories: 00_Inbox/, 01_Projects/, 02_Areas/, 03_Resources/, 04_Archive/, 06_Daily_Logs/.
    • OKF Overlay (Open Knowledge Format): Standardized YAML frontmatter for every note (type, title, description, tags, timestamp).
  • Purpose: Stores persistent memory, lessons learned, architectural decision records (ADRs), execution plans, and session logs.

2. P.O.W.E.R. Framework — Active Engine & AI Toolkit

  • What it is: The Python engine and MCP server (power-framework) engineered specifically for AI agents (Antigravity, OpenCode, Codex) to interact safely and intelligently with the Second Brain.
  • Key Capabilities:
    1. Hybrid Retrieval (RAG): Combines SQLite FTS5 (BM25) full-text search, offline dense vector embeddings (BGE-M3 1024d), and BGE Reranker v2 M3 cross-encoder reranking via Reciprocal Rank Fusion (RRF). Provides sub-second precision without overwhelming LLM context windows.
    2. Vault Health & Linting (power lint): Scans for missing OKF metadata, broken wiki-links, orphan notes, and stale content.
    3. Hierarchical Indexing & GraphRAG (power index): Scans folder structures to automatically generate navigation maps (index.md), per-folder sub-catalogs (_index.md), and Mermaid graph relations.
    4. Auto-Healing & Audit (power heal / power audit): Fixes invalid frontmatter schemas, formats dates/tags, and detects redundant/outdated/trivial notes (ROT Scoring).

3. Collaboration Matrix

Scenario Role of Second Brain Role of P.O.W.E.R. Framework
Session Booting Stores guidelines & MASTER-LESSONS-LEARNED.md. Retrieves relevant lessons and context for the AI agent via search_vault_tool MCP.
Session Ingestion (ingest) Receives new notes under 06_Daily_Logs/YYYY-MM-DD_name.md. Validates OKF frontmatter, checks uniqueness, and appends change entries to log.md.
Structure Maintenance Stores entity relations and project links. Runs power index to rebuild navigation maps and graph relation triplets.
Quality Control (CI/CD) Serves as the single source of truth across fleet hosts (PRXMX, WS, HTZNR). Executes power lint ensuring zero errors before GPG-signed commits and releases.

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/>(BGE-M3 1024d, direct ONNX)"]:::rag
        SQLite[("🗄️ SQLite (FTS5 + chunk_embeddings)")]:::rag
        Expander["🔄 Query Expander (Synonyms / LLM)"]:::rag
        Reranker["🎯 Cross-Encoder Reranker (Jina v2 multilingual)"]:::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: BGE-M3 (default, 1024d, direct ONNX Runtime — BGEM3OnnxManager) / Qwen3-0.6B / MiniLM-L12-v2 (light) via POWER_EMBED_PROVIDER, lazy init, tamed BFCArena, adaptive batch halving on OOM
core/reranker.py Cross-Encoder reranker: onnx-community/bge-reranker-v2-m3-ONNX (default) / Jina v2 (explicit non-commercial opt-in) / Qwen3-Reranker-0.6B-ONNX (provider=qwen3)
core/metrics/discounted_lexical_gain.py Legacy normalized discounted lexical proxy; udcg.py is a deprecated compatibility alias, not EACL-2026 UDCG
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
pytest tests/ -v

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

# Type check
mypy src/power_framework/

Test Reports & Benchmarks

For current, reproducible release information and evidence:

Low-RAM Deployment (8–12 GB)

power sync builds dense vector embeddings for the knowledge vault. Threading and batching limits are fully configurable; test them on target hardware before relying on RAM or latency guarantees. Key configuration knobs:

export POWER_EMBED_PROVIDER=bge-m3           # Default provider (aapot/bge-m3-onnx)
export POWER_EMBED_NUM_THREADS=2             # Cap CPU execution threads
export POWER_EMBED_BATCH_SIZE=8              # Batch size for embedding generation
# export POWER_SYNC_VMEM_LIMIT_MB=6144       # Opt-in virtual-memory limit (RLIMIT_AS)

The canonical default provider is bge-m3 via direct ONNX Runtime + tokenizers (BGEM3OnnxManager), paired with the Apache-2.0 onnx-community/bge-reranker-v2-m3-ONNX reranker. Sync and dense search require validated model assets; if assets are missing or corrupted, retrieval fails closed. Run power sync to fetch or repair pinned model artifacts.

⚠️ Resource note: Adjust POWER_EMBED_NUM_THREADS and POWER_EMBED_BATCH_SIZE for host hardware constraints. Current releases enforce strict fail-closed contract checks; peak memory usage and latency remain hardware-dependent.

License

P.O.W.E.R. Framework is licensed under the GNU General Public License v3.0 (GPLv3).


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

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages