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.

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

Detailed breakdown and technical comparison matrix with competing frameworks:

• ⚡ Why P.O.W.E.R. 3.2.1 Is the Ultimate "Super-Memory" and "Exoskeleton" for Your AI Agents

Quick Start

pip install git+https://github.com/weby-homelab/[email protected]

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

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:

• English: Hierarchical Index Migration Report — performance metrics, architecture, insights
• Українська: Звіт міграції на ієрархічний індекс — повний технічний звіт

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:

• English: AI Agent Migration Guide — 5-phase protocol with MCP tools, classification heuristics, and troubleshooting
• Українська: Ґайд міграції для AI-агента — покроковий протокол для будь-якого AI-агента

🗂️ Methodology Support: Choose What Works for You

P.O.W.E.R. is not locked to a single methodology. Initialize a vault with any popular knowledge organization system in one command:

power init /path/to/vault --template para          # P.A.R.A. — project/deadline focus
power init /path/to/vault --template code          # C.O.D.E. — content synthesis lifecycle
power init /path/to/vault --template gtd           # GTD — inbox processing & task flow
power init /path/to/vault --template zettelkasten  # Zettelkasten — atomic UID idea graph
power init /path/to/vault --template lyt           # LYT — Maps of Content (MOCs)
power init /path/to/vault --template johnny-decimal # Johnny.Decimal — strict numeric hierarchy

OKF metadata validation, BGE-M3 vector search, the linter, and all 12 MCP tools work regardless of the chosen methodology.

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/[email protected]

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

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.

🧠 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

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

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

    %% Sea