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 supports selective agent navigation; the linked historical v1.6.0 report measured scenario-specific savings, not a universal release guarantee
• 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 20 tools to MCP-compatible AI clients through FastMCP 3.x
• Truthful agent discovery — call get_server_info first to verify the running package version, vault boundary, coverage, and explicit provider binding state; the default discovery call performs no model load or network access
• Windows-safe rename — power rename uses os.replace() for the physical move, so renaming onto an existing destination works on Windows instead of raising FileExistsError
• P.O.W.E.R. 3.6.0 release — publication requires a verified wheel, source archive, SBOM, Linux upgrade matrix, and fresh release receipts. Version 3.6.0 consolidates fail-closed doctor, migration, cache, catalog, healer, and agent-contract safeguards. Platform support remains bounded by the support matrix.

For AI Agents

P.O.W.E.R. is designed to be operated by human workflows and AI agents alike. Agents (Antigravity, OpenCode, Claude Code, Gemini, Devin, DeepSeek) should read the role-specific guides before touching a vault:

• Clean installation — isolated runtime, new vault, executable acceptance gate, FTS, and MCP preflight
• Windows 11 25H2 — complete PowerShell installation, Visual C++ prerequisite, exact interpreter paths, and checks
• CLI reference — all 24 commands, flags, and actual exit behavior
• MCP server — all 20 governed tools, rate limits, configured-vault boundary, and untrusted retrieval contract
• Migration guide — 6-phase, manifest/hash-driven migration from any Markdown source methodology into a canonical POWER vault
• Documentation inventory — audited entry points, linked documents, corrected drift, and evidence boundaries
• Platform support matrix — Linux is the v3.6.0 release platform; CI currently validates it on Ubuntu, while macOS and Windows are deferred indefinitely

Quick Start (Linux)

The commands below are the shortest supported path for Linux. They assume Python 3.11+ and a terminal shell; ~/my-vault is the vault directory you want POWER to manage.

v3.6.0 release contract: use the signed tag, wheel, source archive, SBOM, and release receipt only after they appear on the GitHub release page. The URL below is the tag-bound install target, not evidence that publication has already completed. The release receipt covers the declared Linux release boundary; check the support matrix before making platform or model claims about another host.

python3 -m pip install https://github.com/weby-homelab/power-framework/releases/download/v3.6.0/power_framework-3.6.0-py3-none-any.whl

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 (Linux)

Contributors on Linux should clone into a durable development directory, create a venv, and follow CONTRIBUTING.md. Inspect local changes before pulling; documentation does not provide an updater that resets a working tree.

git clone https://github.com/weby-homelab/power-framework.git
cd power-framework
python3 -m venv .venv
source .venv/bin/activate
python -m pip install uv==0.11.33
uv sync --locked --group dev
power --version

Windows 11 25H2 installation (deferred)

Windows 11 25H2 remains outside the v3.6.0 supported-platform boundary. The dedicated Windows 11 25H2 guide describes a separate installation and host-validation path; it is not a Stable release platform certification.

No Windows CI, upgrade-matrix, compatibility, performance, or GPU claim is made for v3.6.0. Windows and macOS have no scheduled release target.

What's Inside

POWER 3.6.0 evidence contract: publication requires machine validation gates, package/CI provenance, an SBOM, a Linux upgrade matrix executed on the Ubuntu CI runner, and source-bound technical receipts. Real-vault and human evaluation are optional benchmarks, not release secrets or publication blockers. Once published, these receipts apply to the declared release scope. Historical feature-table figures, model comparisons, resource limits, and benchmark recommendations do not become guarantees for an arbitrary host or vault.

Migration Report

Read the historical v1.6.0 snapshot of the transition from flat to hierarchical indexing. Its measured vault counts, token estimates, source paths, test counts, and MCP inventory are historical evidence, not the current v3.6.0 contract:

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

AI Agent Migration Guide

Six-phase, fail-closed protocol for any AI agent to migrate an existing Markdown knowledge base into the canonical P.O.W.E.R. structure with an immutable source, verified backup, manifest, body/attachment hashes, link reconciliation, executable gates, and rollback record:

• English: AI Agent Migration Guide — current 6-phase protocol and real MCP/CLI boundaries
• Українська: Ґайд міграції для AI-агента — покроковий протокол для будь-якого AI-агента

🗂️ Methodology compatibility

P.A.R.A., C.O.D.E., GTD, Zettelkasten, LYT, Johnny.Decimal, flat, and custom trees are supported as source methodologies for migration. Full P.O.W.E.R. hierarchical navigation uses the canonical top-level folders created by power init; MCP note writes and sub-index reads also enforce their documented canonical scope. Follow the migration guide instead of assuming an arbitrary existing tree already has the full POWER contract.

Lint and content search can inspect valid notes outside canonical folders, but power index catalogs only 00_Inbox, 01_Projects, 02_Areas, 03_Resources, 04_Archive, 06_Daily_Logs, and PROTOCOLS. This distinction prevents a partial in-place adoption from being described as a completed migration.

Domain-first placement and retrieval

For domain routing inside the canonical vault, create .power/domains.yaml and keep directory and filename names meaningful: these are the first navigation signals for an AI agent. OKF frontmatter remains the validated provenance and lifecycle contract, not the only routing mechanism. A minimal registry is:

version: 1
domains:
    - name: research
      path: 03_Resources/research
      template: 05_Templates/research.md
      rules:
          - keywords: [paper, experiment]
            weight: 2
          - tags: [science]
      search_priority: [fts, semantic]

Keep domain paths under a cataloged canonical folder, as in the example. power ingest routes by these rules (or accepts --domain research) and uses the selected template. power search ... --mode auto --domain research follows the domain priority and scopes candidates to the domain path. Only retrieval modes implemented by POWER are accepted; unsupported providers such as Qdrant are rejected instead of being advertised as available. Without a registry, legacy P.A.R.A. placement is unchanged; the default auto profile uses verified dense only when ready and otherwise returns labelled FTS.

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 cache list|prune <path>  Inspect or explicitly prune rebuildable cache namespaces
power doctor [path]            Read-only runtime and index diagnosis
power connect [path]           Plan/apply conflict-safe local MCP client setup
power search <path> <query>    Full-text search with relevance scoring
power ingest <path> [options]  Create a new note with validated OKF metadata
power import <dir> --into FOLDER [options]
                                Preflight/import an existing Markdown tree
power memory <operation>       Governed memory context, proposal, apply, validation, and history
power handoff <operation>      Durable cross-agent work packets and proof-carrying resume
power sync <path>              Build FTS and dense search indexes
power rot <path>               ROT Audit — detect redundant, outdated, trivial notes
power status [path]            Show vault status dashboard (statistics & health metrics)
power control-plane <path>     Preview/materialize the content-free control cockpit
power maintenance <path>      Preview or explicitly apply hash-bound maintenance
power migrate-state <path>    Inspect source/control/runtime/evidence state without writes
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 cron <path>              Run read-only maintenance plus rebuildable index projection
power suggest-related <path>   Suggest cross-note relations for Graph RAG
power synthesize <path>        Auto-ingest a session synthesis note
power rename <path> --old OLD --new NEW   Rename a note and update related paths

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"
power ingest ~/my-vault --type Resource --title "Experiment Notes" --description "Research experiment" --domain research

Search Examples

power search ~/my-vault "api authentication"
power search ~/my-vault "deployment guide" --max-results 5
power search ~/my-vault "experiment" --mode auto --domain research

MCP Server Setup

Connect P.O.W.E.R. to any MCP-compatible AI client (local stdio or Docker HTTP transport). The MCP client onboarding guide contains the canonical configurations for Claude Desktop/Code, Gemini CLI, Codex, and OpenCode, plus the read-only golden task and approval workflow.

The wheel URL below is the tag-bound v3.6.0 install target. Run it only after the signed tag and assets exist on the release page with the source archive, SBOM, and release receipts.

pip install https://github.com/weby-homelab/power-framework/releases/download/v3.6.0/power_framework-3.6.0-py3-none-any.whl

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"],
    "environment": {
      "POWER_VAULT_DIR": "/path/to/your/my-vault"
    },
    "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; the historical v1.6 migration report records scenario-specific measurements, not a current release guarantee

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.
• 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. Historical v1.6 measurements are preserved in the migration report and are not a current release-quality claim.
• 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 & ROT audit (power heal / power rot): Fixes invalid frontmatter schemas and detects redundant, outdated, or trivial notes.

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 (BGE reranker v2 M3)"]:::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[["🔌 20 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

Core Library (src/power_framework/)