{"id":51819213,"url":"https://github.com/weby-homelab/power-framework","last_synced_at":"2026-07-22T03:05:29.883Z","repository":{"id":368820630,"uuid":"1287015444","full_name":"weby-homelab/power-framework","owner":"weby-homelab","description":"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","archived":false,"fork":false,"pushed_at":"2026-07-21T23:23:32.000Z","size":1043,"stargazers_count":12,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-21T23:27:53.302Z","etag":null,"topics":["ai-agents","execution-rules","homelab","knowledge-management","llm-wiki","mcp","obsidian","okf","para","python","second-brain","self-hosted"],"latest_commit_sha":null,"homepage":"https://weby-homelab.github.io/power-framework/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weby-homelab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["weby-homelab"],"custom":["https://github.com/weby-homelab"]}},"created_at":"2026-07-02T09:50:59.000Z","updated_at":"2026-07-21T22:08:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"af600fb4-7581-438f-8678-c05b449b4a0a","html_url":"https://github.com/weby-homelab/power-framework","commit_stats":null,"previous_names":["weby-homelab/p.o.w.e.r","weby-homelab/power-framework"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/weby-homelab/power-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weby-homelab%2Fpower-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weby-homelab%2Fpower-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weby-homelab%2Fpower-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weby-homelab%2Fpower-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weby-homelab","download_url":"https://codeload.github.com/weby-homelab/power-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weby-homelab%2Fpower-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35744650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","execution-rules","homelab","knowledge-management","llm-wiki","mcp","obsidian","okf","para","python","second-brain","self-hosted"],"created_at":"2026-07-22T03:05:29.244Z","updated_at":"2026-07-22T03:05:29.874Z","avatar_url":"https://github.com/weby-homelab.png","language":"Python","funding_links":["https://github.com/sponsors/weby-homelab","https://github.com/weby-homelab"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cb\u003eENG\u003c/b\u003e | \u003ca href=\"README.ua.md\"\u003eUKR\u003c/a\u003e\n\u003c/p\u003e\n\n# P.O.W.E.R. — AI-Native Toolkit for Second Brain\n\nValidate, 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.\n\n[![CI](https://github.com/weby-homelab/power-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/weby-homelab/power-framework/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-73%25-yellow?logo=pytest)](https://github.com/weby-homelab/power-framework/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/weby-homelab/power-framework?logo=github)](https://github.com/weby-homelab/power-framework/releases)\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![CodeQL](https://github.com/weby-homelab/power-framework/actions/workflows/codeql.yml/badge.svg)](https://github.com/weby-homelab/power-framework/actions/workflows/codeql.yml)\n[![Docs](https://img.shields.io/badge/docs-mkdocs--material-8A2BE2?logo=materialformkdocs)](https://weby-homelab.github.io/power-framework/)\n\n## About P.O.W.E.R. - Hybrid Knowledge Management Framework\n\nP.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., **O**KF, **W**iki, and **E**xecution **R**ules. It integrates these distinct architectural frameworks to construct a coherent, self-validating, and token-efficient Second Brain.\n\n## Why P.O.W.E.R.?\n\nUnlike generic knowledge management tools, P.O.W.E.R. is designed from the ground up for **AI-first knowledge management**:\n\n- **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`)\n- **Token-efficient indexing** — hierarchical `index.md` + per-folder `_index.md` cuts AI agent context usage by ~75%\n- **Knowledge Graph** — `related` field connects notes across the vault; visualized in sub-indexes for Graph RAG workflows\n- **Freshness Monitoring** — linter detects stale/expired notes based on `expiry` metadata field\n- **Agent Auto-Ingest** — `synthesize_session` MCP tool lets agents autonomously create permanent knowledge artifacts with governance + graph links + full catalog maintenance\n- **MCP-native** — expose all 12 tools to any MCP-compatible AI client (Claude, OpenCode, Cursor) with zero glue code, powered by FastMCP 3.x\n- **Production-grade** — 416 tests, 73%+ coverage (CI `fail-under=70`), CodeQL scanning, Automated GitHub Releases\n\n## Quick Start\n\n```bash\npip install git+https://github.com/weby-homelab/power-framework.git@v3.0.0\n\npower init ~/my-vault          # Create vault structure\npower lint ~/my-vault          # Check for broken links \u0026 missing metadata\npower index ~/my-vault         # Generate catalog index.md\npower heal ~/my-vault          # Auto-fix missing/invalid frontmatter\npower markdown-check ~/my-vault  # Check markdown quality issues\n```\n\n## Development Install (editable + easy update)\n\nFor a **permanent, always-updatable** CLI on your workstation (WS), install in\n_editable_ mode from a local clone. This binds `power` to the repo so code\nchanges take effect immediately — no reinstall needed.\n\n```bash\n# 1. Clone once\ngit clone https://github.com/weby-homelab/power-framework.git /tmp/power-framework\ncd /tmp/power-framework\n\n# 2. Editable install into user-site (survives reboots, no venv required)\npip install --user --break-system-packages -e \".[dev]\"\n\n# 3. Verify — `power` is now on PATH (via ~/.local/bin)\npower --version\n```\n\nUpdate to the latest code anytime with:\n\n```bash\ncd /tmp/power-framework \u0026\u0026 git pull origin main \u0026\u0026 power --version\n# If pyproject.toml changed (new deps/version), reinstall:\npip install --user --break-system-packages -e \".[dev]\"\n```\n\n\u003e 💡 **One-liner updater.** Save this as `/root/.local/bin/power-update` and\n\u003e `chmod +x` it, then just run `power-update` to pull + reinstall automatically:\n\u003e\n\u003e ```bash\n\u003e #!/usr/bin/env bash\n\u003e set -euo pipefail\n\u003e REPO=\"/tmp/power-framework\"\n\u003e cd \"$REPO\"\n\u003e git fetch origin main \u0026\u0026 git reset --hard origin/main\n\u003e if git diff --name-only HEAD@{1} HEAD | grep -q pyproject.toml; then\n\u003e   pip install --user --break-system-packages -e \".[dev]\" \u003e/dev/null 2\u003e\u00261\n\u003e fi\n\u003e power --version\n\u003e ```\n\n## What's Inside\n\n| Feature                         | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |\n| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **CLI**                         | `power init`, `lint`, `index`, `ingest`, `search`, `rot`, `status`, `archive`, `cron`, `heal`, `markdown-check`, `suggest-related` — 12 commands for full vault management                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n| **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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| **OKF Validation**              | Pydantic v2 schemas enforce strict metadata on every note with governance (`owner`, `status`, `expiry`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| **Knowledge Graph (Graph RAG)** | `related` field in OKF frontmatter supporting `TypedRelation` (path, relation, confidence) with BFS traversal and Mermaid diagram export (`to_mermaid`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| **Freshness Monitoring**        | Linter flags stale/expired notes by checking `expiry` dates, ensuring your vault stays current                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |\n| **Agent Auto-Ingest**           | `synthesize_session` MCP tool — agents autonomously create permanent notes with governance + graph links + full index rebuild                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| **ROT Audit**                   | Detects redundant, outdated, and trivial notes using dense embedding semantic deduplication and LLM fact contradiction checks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| **Auto-Archive**                | Automatically archives stale notes to `04_Archive/` — `power archive \u003cpath\u003e` with dry-run preview                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| **Healer**                      | Auto-fixes missing/invalid frontmatter fields (title, description, type, timestamp) — `power heal \u003cpath\u003e`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| **Markdown Checks**             | Detects trailing whitespace, inconsistent list markers, header jumps, missing code language — `power markdown-check \u003cpath\u003e`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |\n| **Relation Suggestions**        | Keyword \u0026 tag overlap analysis for Graph RAG enrichment — `power suggest-related \u003cpath\u003e`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |\n| **Cron Maintenance**            | Runs lint + index + rot audit in one command — `power cron \u003cpath\u003e`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| **Advanced Hybrid Search**      | FTS5 (BM25), Dense Vector Semantic, Hybrid (RRF fusion), Semantic, and **Reranked** (canonical, default) modes. **POWER 3.0 canonical mode is `reranked`**: FTS5/BM25 → top-150 candidates → cross-encoder reranker → top-20, with a dense-embedding fallback only when FTS yields \u003c 5 hits. **Canonical dense backend: `BAAI/bge-m3` (1024d)** served via **direct ONNX Runtime** (no fastembed, no PyTorch) — the only backend with strong UA↔EN retrieval (vector MAR@5 ≈ 0.573 UA→EN, isolated cross-lingual cosine ≈ 0.771 UA→EN, nDCG@5 ≈ 0.80 on the real vault), peak RSS ≈ 1.6 GB. Includes synonym query expansion and Contextual Retrieval chunking (`SemanticChunker`). Legacy `fastembed`/`qwen3` backends remain opt-in via `POWER_EMBED_PROVIDER`. **Note (3.0.0 benchmark):** for bilingual UA/EN vaults, **`hybrid`** (no reranker) is recommended — the English-centric cross-encoder reranker degrades Ukrainian (UA ndcg@5 ≈ 0.44 vs hybrid ≈ 0.82); see `docs/tests/P.O.W.E.R.3.0.0-TEST.md`. |\n| **Cross-Encoder Reranker**      | `reranked` mode uses the multilingual **`jinaai/jina-reranker-v2-base-multilingual`** by default. Fixes the old MiniLM reranker which degraded mix-lingual quality (MAR@5 −22%, ×8 latency). With `POWER_EMBED_PROVIDER=qwen3` it uses `Qwen3-Reranker-0.6B-ONNX`; `fastembed` falls back to `ms-marco-MiniLM-L-6-v2`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| **Hierarchical Index**          | `index.md` (navigation map) + per-folder `_index.md` (detailed catalogs) for token-efficient AI reading (~75-94% token savings)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| **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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| **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** and the canonical Jina v2 reranker remains the fallback.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |\n| **Synthesize Auto-Ingest**      | Phase 3 `power synthesize \u003cpath\u003e` 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| **UDCG Search-Quality Gate**    | Phase 3 search-quality CI uses **UDCG@5** (primary gate) plus **nDCG@5** (secondary). On the real vault: nDCG@5 ≈ 0.80, UDCG@5 ≈ 0.99 (PASS).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| **CI/CD**                       | 416 tests, 73%+ coverage, CodeQL SAST, Automated GitHub Releases                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| **Documentation**               | Full [mkdocs-material site](https://weby-homelab.github.io/power-framework/) with API reference and guides                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |\n\n## Migration Report\n\nRead the full technical report on the transition from flat to hierarchical indexing:\n\n- **[English: Hierarchical Index Migration Report](https://github.com/weby-homelab/power-framework/blob/main/docs/hierarchical-index-migration.md)** — performance metrics, architecture, insights\n- **[Українська: Звіт міграції на ієрархічний індекс](https://github.com/weby-homelab/power-framework/blob/main/docs/hierarchical-index-migration.ua.md)** — повний технічний звіт\n\n### AI Agent Migration Guide\n\nStep-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:\n\n- **[English: AI Agent Migration Guide](https://github.com/weby-homelab/power-framework/blob/main/docs/migration-guide.md)** — 5-phase protocol with MCP tools, classification heuristics, and troubleshooting\n- **[Українська: Ґайд міграції для AI-агента](https://github.com/weby-homelab/power-framework/blob/main/docs/migration-guide.ua.md)** — покроковий протокол для будь-якого AI-агента\n\n## Who Is This For\n\n- **Knowledge workers** who want AI agents to understand and maintain their knowledge base\n- **Developers** building a structured Second Brain with machine-readable metadata\n- **Teams** that need consistent note formatting and automated quality checks\n\n## Commands\n\n```\npower init \u003cpath\u003e              Create a new vault with P.A.R.A. folder structure\npower lint \u003cpath\u003e              Scan for broken links, missing metadata, orphans\npower index \u003cpath\u003e             Generate hierarchical index (index.md + _index.md files)\npower search \u003cpath\u003e \u003cquery\u003e    Full-text search with relevance scoring\npower ingest \u003cpath\u003e [options]  Create a new note with validated OKF metadata\npower rot \u003cpath\u003e               ROT Audit — detect redundant, outdated, trivial notes\npower status [path]            Show vault status dashboard (statistics \u0026 health metrics)\npower heal \u003cpath\u003e              Auto-heal missing/invalid frontmatter\npower markdown-check \u003cpath\u003e    Check markdown quality issues\npower archive \u003cpath\u003e           Auto-archive stale notes to 04_Archive/\npower suggest-related \u003cpath\u003e   Suggest cross-note relations for Graph RAG\npower cron \u003cpath\u003e              Run automated maintenance (lint + index + rot)\n```\n\n### Ingest Examples\n\n```bash\npower ingest ~/my-vault --type Project --title \"My App\" --description \"A new project\"\npower ingest ~/my-vault --type Resource --title \"Docker Guide\" --description \"Docker best practices\" --tags devops,docker --resource \"https://docs.docker.com\"\n```\n\n### Search Examples\n\n```bash\npower search ~/my-vault \"api authentication\"\npower search ~/my-vault \"deployment guide\" --max-results 5\n```\n\n## MCP Server Setup\n\nConnect P.O.W.E.R. to any MCP-compatible AI client (local stdio or Docker HTTP transport).\n\n```bash\npip install git+https://github.com/weby-homelab/power-framework.git@v3.0.0\n```\n\n**Claude Desktop** (`~/.config/Claude/claude_desktop_config.json`):\n\n```json\n{\n    \"mcpServers\": {\n        \"power\": {\n            \"command\": \"python3\",\n            \"args\": [\"-m\", \"power_framework.mcp\"],\n            \"env\": {\n                \"POWER_VAULT_DIR\": \"/path/to/your/my-vault\"\n            }\n        }\n    }\n}\n```\n\n**OpenCode** (`~/.config/opencode/opencode.jsonc`):\n\n```jsonc\n\"mcp\": {\n  \"power\": {\n    \"type\": \"local\",\n    \"command\": [\"python3\", \"-m\", \"power_framework.mcp\"],\n    \"enabled\": true\n  }\n}\n```\n\n## Vault Structure\n\nP.O.W.E.R. organizes your vault using the **P.A.R.A.** method with **OKF metadata** on every note:\n\n```\n~/my-vault\n├── 00_Inbox/\n│   └── _index.md        # Detailed sub-index for Inbox notes\n├── 01_Projects/\n│   └── _index.md        # Detailed sub-index for Projects\n├── 02_Areas/\n│   └── _index.md        # Detailed sub-index for Areas\n├── 03_Resources/\n│   └── _index.md        # Detailed sub-index for Resources\n├── 04_Archive/\n│   └── _index.md        # Detailed sub-index for Archive\n├── 05_Templates/        # Note templates with OKF frontmatter\n├── 06_Daily_Logs/\n│   └── _index.md        # Detailed sub-index for Daily Logs\n├── PROTOCOLS/           # System specs for AI agents\n├── index.md             # Navigation map (links to sub-indexes)\n└── log.md               # Append-only change log\n```\n\n### Hierarchical Index Protocol\n\nAI agents read the vault efficiently by following this pattern:\n\n1. **Read `index.md`** — identify the relevant category by note counts\n2. **Call `read_sub_index` MCP tool** — get detailed entries for that category\n3. **Read specific notes** — only when the sub-index indicates relevance\n4. **NEVER glob all `.md` files** — use sub-indexes as a map (~75% token savings)\n\nEvery note starts with validated YAML frontmatter. Core fields + optional governance and graph links:\n\n```yaml\n---\ntype: Project\ntitle: \"My App\"\ndescription: \"A new project with clear goals\"\ntags: [active, dev]\ntimestamp: 2026-07-02T19:00:00\nowner: \"team-alpha\" # optional: governance — responsible owner\nstatus: active # optional: active | review | archived\nexpiry: 2026-12-31 # optional: freshness management\nrelated:\n    - path: 01_Projects/Other.md\n      relation: depends_on # optional: relation type\n      confidence: 1.0 # optional: confidence score\n---\n```\n\n## Architecture Details\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eP.O.W.E.R. Methodology — click to expand\u003c/strong\u003e\u003c/summary\u003e\n\nThe framework combines four complementary methodologies:\n\n- **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.\n- **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.\n- **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%.\n- **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.\n\n### Visual Framework Diagram\n\n```mermaid\nflowchart TD\n    %% Modern 2026 Styling\n    classDef human fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#fff,rx:8\n    classDef data fill:#0ea5e9,stroke:#0369a1,stroke-width:2px,color:#fff,rx:8\n    classDef wiki fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff,rx:8\n    classDef rag fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff,rx:8\n    classDef agent fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#fff,rx:8\n    classDef security fill:#ef4444,stroke:#b91c1c,stroke-width:2px,color:#fff,rx:8\n\n    subgraph Human [\"👤 Human (Markdown UI)\"]\n        PARA[[\"📁 P.A.R.A. Directory Structure\"]]:::human\n    end\n\n    subgraph OKF [\"📄 OKF Overlay (Metadata \u0026 GraphRAG Schema)\"]\n        YAML[/\"📝 YAML Frontmatter with Typed Relations\"\\]:::data\n    end\n\n    subgraph RAG [\"🔍 RAG \u0026 GraphRAG Pipeline\"]\n        Chunker[\"✂️ Semantic Chunker (Anthropic Contextual)\"]:::rag\n        Embeddings[\"🧠 Dense Embeddings\u003cbr/\u003e(BGE-M3 1024d, direct ONNX)\"]:::rag\n        SQLite[(\"🗄️ SQLite (FTS5 + chunk_embeddings)\")]:::rag\n        Expander[\"🔄 Query Expander (Synonyms / LLM)\"]:::rag\n        Reranker[\"🎯 Cross-Encoder Reranker (Jina v2 multilingual)\"]:::rag\n        KG[\"🕸️ Knowledge Graph (BFS / Mermaid Graph)\"]:::rag\n    end\n\n    subgraph Wiki [\"📖 LLM-Wiki (Hierarchical Catalog)\"]\n        IndexMD[(\"🗂️ index.md (Navigation Map)\")]:::wiki\n        SubIndex[(\"📂 _index.md (Per-Folder Details)\")]:::wiki\n        LogMD[(\"📜 log.md (Change Log)\")]:::wiki\n    end\n\n    subgraph AI [\"🤖 AI Agent (FastMCP 3.x)\"]\n        Tools[[\"🔌 12 Async MCP Tools (stdio/HTTP)\"]]:::agent\n        Search[[\"🔍 Hybrid / Reranked Search\"]]:::agent\n        ROT{{\"🛠️ ROT \u0026 Contradiction Audit (Semantic/LLM)\"}}:::agent\n    end\n\n    subgraph ER [\"🔐 Execution Rules\"]\n        GPG((\"🔑 GPG-Signed Commits\")):::security\n        PR((\"🛡️ PR-Only Workflow\")):::security\n        Sync((\"⏱️ Cron Auto-Sync\")):::security\n    end\n\n    %% Data Flow\n    Human -- \"Writes Notes\" --\u003e PARA\n    PARA -- \"Enforces OKF\" --\u003e YAML\n    YAML -- \"Parsed by\" --\u003e Chunker\n\n    %% RAG Pipeline\n    Chunker -- \"Contextual Chunks\" --\u003e Embeddings\n    Embeddings -- \"Stores Vectors\" --\u003e SQLite\n\n    %% Search Pipeline\n    Tools -- \"Issues Query\" --\u003e Expander\n    Expander -- \"Multi-Queries\" --\u003e SQLite\n    SQLite -- \"FTS5 + Vector Candidates\" --\u003e Reranker\n    Reranker -- \"Top Ranked Results\" --\u003e Search\n\n    %% GraphRAG Pipeline\n    YAML -- \"Defines Edges\" --\u003e KG\n    KG -- \"Renders Subgraphs\" --\u003e Tools\n\n    %% Wiki Operations\n    Tools -- \"Auto-Ingests \u0026 Indexes\" --\u003e IndexMD\n    Tools -- \"Updates\" --\u003e SubIndex\n    Tools -- \"Appends Logs\" --\u003e LogMD\n\n    %% ROT Audit\n    Tools -- \"Runs Audit\" --\u003e ROT\n    ROT -- \"Deduplicates\" --\u003e Embeddings\n    ROT -- \"Checks Conflicts\" --\u003e SQLite\n\n    %% Sync \u0026 Security\n    IndexMD -. \"Synced via\" .-\u003e Sync\n    SubIndex -. \"Synced via\" .-\u003e Sync\n    LogMD -. \"Synced via\" .-\u003e Sync\n    Sync -- \"Triggers\" --\u003e GPG\n    GPG -- \"Enforces\" --\u003e PR\n```\n\n### Core Library (`src/power_framework/`)\n\n| Module                    | Purpose                                                                                                                                                                                                                            |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `core/models.py`          | Pydantic v2 schemas for OKF metadata validation                                                                                                                                                                                    |\n| `core/parser.py`          | Safe YAML frontmatter parsing (PyYAML-based)                                                                                                                                                                                       |\n| `core/indexer.py`         | Vault scanning and hierarchical index generation                                                                                                                                                                                   |\n| `core/linter.py`          | Health checks: broken links, missing metadata, orphans, stale/expired notes                                                                                                                                                        |\n| `core/searcher.py`        | Full-text search with relevance scoring (FTS5/Vector/Hybrid/Reranked); WAL mode + `busy_timeout` for parallel access                                                                                                               |\n| `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 |\n| `core/reranker.py`        | Cross-Encoder reranker: **`jina-reranker-v2-base-multilingual`** (default) / `Qwen3-Reranker-0.6B-ONNX` (provider=qwen3) / `ms-marco-MiniLM-L-6-v2` fallback                                                                       |\n| `core/metrics/udcg.py`    | UDCG retrieval metric (EACL 2026) — utility-aware replacement for MRR/nDCG for LLM RAG evaluation                                                                                                                                  |\n| `core/query_expansion.py` | Synonym map (EN/UK) \u0026 OpenRouter Multi-Query expansion                                                                                                                                                                             |\n| `core/chunker.py`         | Semantic \u0026 contextual note splitter (Anthropic Contextual Retrieval)                                                                                                                                                               |\n| `core/healer.py`          | Auto-fix missing/invalid frontmatter fields                                                                                                                                                                                        |\n| `core/relations.py`       | KnowledgeGraph builder, BFS traversal, and Mermaid exporter                                                                                                                                                                        |\n| `core/rot_scoring.py`     | A2 scoring: semantic content dedup, freshness, contradiction checks                                                                                                                                                                |\n| `core/markdown_checks.py` | Markdown quality checks: trailing whitespace, list markers, header jumps                                                                                                                                                           |\n| `core/constants.py`       | Centralized exclusion lists and system constants                                                                                                                                                                                   |\n| `core/utils.py`           | Path traversal protection, atomic writes, backups, rate limiter                                                                                                                                                                    |\n| `core/cli.py`             | Command-line interface (12 commands via argparse)                                                                                                                                                                                  |\n| `mcp/power_server.py`     | FastMCP 3.x server with 12 async tools + HTTP transport + /health                                                                                                                                                                  |\n\nAll components share `power_framework.core` as the single source of truth.\n\n\u003c/details\u003e\n\n## Development\n\n```bash\ngit clone https://github.com/weby-homelab/power-framework.git\ncd power-framework\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\n\n# Run tests (416 tests, 73%+ coverage)\npytest tests/ -v\n\n# Lint \u0026 format\nruff check src/ tests/\nruff format src/ tests/\n\n# Type check\nmypy src/power_framework/\n```\n\n### Test Reports \u0026 Benchmarks\n\nFor detailed analysis and benchmarks of the P.O.W.E.R. framework:\n\n- [P.O.W.E.R. v2.0.1 Test Report \u0026 Speed Benchmarks](docs/tests/P.O.W.E.R.2.0.1-TEST-1.md) — Multi-lingual (UA/EN) embeddings via `BAAI/bge-m3`, test run outputs, and memory overhead optimization.\n- [Vector Search Degradation \u0026 Scalability Limits Analysis](docs/tests/P.O.W.E.R.2.0.1-TEST-2.md) — Comparison of linear NumPy search vs SIMD C `sqlite-vec`, graph-based HNSW, and Qdrant database.\n- [AI Agent Memory Benchmark \u0026 SOTA Competency Report (v2.0.3-TEST)](docs/tests/P.O.W.E.R.2.0.3-TEST.md) — Multi-turn incremental evaluations covering MemoryAgentBench (ICLR 2026), LoCoMo, LongMemEval, and BEAM.\n- [P.O.W.E.R. v3.0.0 — Extended UA↔EN Search-Quality Report](docs/tests/P.O.W.E.R.3.0.0-TEST.md) — POWER 3.0.0 stack (BGE-M3 canonical, reranked/hybrid modes, UDCG@5 primary gate, Graph RAG v2, ColBERT opt-in), per-language breakdown, version/architecture evolution, and DRAPAS vs POWER 3.0.0 comparison.\n\n## Low-RAM Deployment (8–12 GB)\n\n`power sync` builds dense embeddings for the whole vault. To stay safely under\nRAM limits on small hosts, v2.2.0 batches embeddings and degrades gracefully\ninstead of crashing. Key knobs (see [`OOM_RECOVERY_PROTOCOL.md`](OOM_RECOVERY_PROTOCOL.md)):\n\n```bash\nexport POWER_EMBED_PROVIDER=bge-m3           # default: BAAI/bge-m3 (1024d, direct ONNX, ~1.6 GB peak RSS)\nexport POWER_EMBED_NUM_THREADS=2             # cap CPU threads on low-core boxes (also tames the ONNX arena)\nexport POWER_EMBED_BATCH_SIZE=8              # peak RAM bound; halves automatically on pressure\n# export POWER_SYNC_VMEM_LIMIT_MB=6144       # opt-in hard backstop (0 = disabled; recommended on large hosts)\n```\n\nThe **POWER 3.0 canonical backend** is **`BAAI/bge-m3`** (1024d) served through\n**direct ONNX Runtime + `tokenizers`** (`BGEM3OnnxManager`) — deliberately NOT\nthrough fastembed, whose custom-model registry cannot resolve BGE-M3's ONNX\nexternal-data files (it broke the embedder across 15 releases). BGE-M3 is the\nonly backend with strong UA↔EN retrieval (MAR@5 ≈ 0.573, cross-lingual cosine\n≈ 0.771 UA→EN) and, with the tamed BFCArena\n(`enable_cpu_mem_arena=False`, `arena_extend_strategy=kSameAsRequested`), keeps\npeak RSS ≈ 1.6 GB — inside the POWER 3.0 **≤2 GB** contract. On very tight hosts\nfall back to `POWER_EMBED_PROVIDER=fastembed` (MiniLM-L12, 384d, lower quality).\n\n\u003e **⚠️ `POWER_EMBED_NUM_THREADS` is mandatory on big hosts.** fastembed's\n\u003e `parallel=0` spawns one model subprocess **per CPU core**. On a 20-core box\n\u003e that loaded 20 copies of the model → **~32 GB RSS**. POWER now caps this to\n\u003e `POWER_EMBED_NUM_THREADS` (default 2, peak ~700 MB). Never raise it above\n\u003e what your RAM allows (cores × ~1.5 GB).\n\n## License\n\nGPLv3 — Built in Ukraine ⚡\n\n\u003cp align=\"center\"\u003e\n  Built in Ukraine under air raid sirens \u0026amp; blackouts ⚡\u003cbr\u003e\n  \u0026copy; 2026 Weby Homelab\n\u003c/p\u003e\n\n\u003c!--\nAI-INDEXING: ALLOWED | CRAWLER-PRIORITY: HIGH | CONTENT-TYPE: OPEN-SOURCE-TOOLKIT\nMACHINE-READABLE-METADATA: JSON-LD BELOW\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"SoftwareApplication\",\n  \"name\": \"P.O.W.E.R. Framework\",\n  \"alternateName\": \"power-framework\",\n  \"description\": \"AI-native Python toolkit for Second Brain knowledge bases. Validate, index, search, and manage Obsidian vaults via CLI or MCP server using the P.A.R.A. + OKF methodology.\",\n  \"url\": \"https://github.com/weby-homelab/power-framework\",\n  \"downloadUrl\": \"https://github.com/weby-homelab/power-framework/releases\",\n  \"applicationCategory\": \"DeveloperApplication\",\n  \"operatingSystem\": \"Linux, macOS, Windows\",\n  \"programmingLanguage\": \"Python\",\n  \"runtimePlatform\": \"Python 3.10+\",\n  \"softwareVersion\": \"latest\",\n  \"license\": \"https://www.gnu.org/licenses/gpl-3.0\",\n  \"keywords\": [\"second-brain\", \"obsidian\", \"AI\", \"MCP\", \"knowledge-management\", \"PARA\", \"CLI\", \"LLM\", \"RAG\", \"knowledge-base\"],\n  \"author\": {\n    \"@type\": \"Organization\",\n    \"name\": \"Weby Homelab\",\n    \"url\": \"https://github.com/weby-homelab\"\n  },\n  \"codeRepository\": \"https://github.com/weby-homelab/power-framework\",\n  \"documentationUrl\": \"https://weby-homelab.github.io/power-framework/\",\n  \"isAccessibleForFree\": true,\n  \"offers\": {\n    \"@type\": \"Offer\",\n    \"price\": \"0\",\n    \"priceCurrency\": \"USD\"\n  }\n}\n--\u003e\n\n\u003c!--\nAI-INDEXING: ALLOWED | CRAWLER-PRIORITY: HIGH | CONTENT-TYPE: OPEN-SOURCE-TOOL\n\n@context: https://schema.org\n@type: SoftwareApplication\nname: P.O.W.E.R. — Hybrid Knowledge Management Framework\nalternateName: power-framework\ndescription: P.O.W.E.R. - Hybrid Knowledge Management Framework (P.A.R.A. + OKF Overlay + LLM-Wiki + Execution Rules)\napplicationCategory: DeveloperApplication\napplicationSubCategory: KnowledgeManagement\noperatingSystem: Linux\nsoftwareVersion: 3.0.0\nkeywords: knowledge-management, second-brain, obsidian, para, okf, llm-wiki, mcp, ai-agents, python, execution-rules\nauthor: Weby Homelab (https://github.com/weby-homelab)\ncodeRepository: https://github.com/weby-homelab/power-framework\ndownloadUrl: https://github.com/weby-homelab/power-framework/releases\nlicense: GPL-3.0\nisAccessibleForFree: true\n--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweby-homelab%2Fpower-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweby-homelab%2Fpower-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweby-homelab%2Fpower-framework/lists"}