PowerContext integration for WorkBuddy

This directory contains a thin WorkBuddy integration backed by a running PowerContext server. It does not embed storage or start the server. WorkBuddy keeps the user interface and agent orchestration while PowerContext provides external storage, retrieval, context preparation, Memory, and Handoff lifecycle operations.

The integration has three capability layers:

• a UserPromptSubmit hook asks the Runtime to prepare one final, bounded context value before WorkBuddy analyzes the prompt, then independently captures the prompt as Source evidence;
• Streamable HTTP MCP at http://127.0.0.1:8000/mcp gives WorkBuddy explicit Memory and work-continuity tools (search_memory, list_memory_entries, handoff_current_work, commit_handoff, and so on);
• the project-context Skill turns an imperative such as 交接, 交接当前工作, or handoff this work into one durable, committed Handoff, and restores project memory for continued work.

The hooks driver is pure Python 3.11+ standard library and needs no extra dependencies. WorkBuddy support ships with a powercontext setup workbuddy CLI installer; the manual steps below remain available as a fallback.

Install with the PowerContext CLI

Install the hooks, MCP server, and Skill from a local checkout or a GitHub source in one step:

powercontext setup workbuddy --source oceanbase/powercontext --ref master

For a local checkout, point --source at the repository root or the plugin directory:

powercontext setup workbuddy --source /path/to/powercontext

The installer copies the hook driver, its settings modules, and the scope resolver into ~/.workbuddy/hooks, merges the UserPromptSubmit hook into ~/.workbuddy/settings.json, registers the powercontext server in ~/.workbuddy/mcp.json, and installs the project-context Skill under ~/.workbuddy/skills. Existing settings and other MCP servers are preserved, and the Skill's command placeholders are resolved automatically. Verify the result with powercontext doctor workbuddy.

PLUGIN=integrations/workbuddy/plugins/powercontext
WORKBUDDY_HOOKS_DIR="${WORKBUDDY_HOOKS_DIR:-$HOME/.workbuddy/hooks}"

mkdir -p "$WORKBUDDY_HOOKS_DIR"
cp "$PLUGIN"/hooks/workbuddy_powercontext_hook.py \
   "$PLUGIN"/hooks/workbuddy_settings.py \
   "$PLUGIN"/hooks/prepared_context.py \
   "$WORKBUDDY_HOOKS_DIR"/
cp "$PLUGIN/scripts/project_scope.py" \
   "$WORKBUDDY_HOOKS_DIR/powercontext_project_scope.py"

<WORKBUDDY_HOOKS_DIR>/
  workbuddy_powercontext_hook.py
  workbuddy_settings.py
  prepared_context.py
  powercontext_project_scope.py

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"<POWERCONTEXT_PYTHON>\" \"<WORKBUDDY_HOOKS_DIR>/workbuddy_powercontext_hook.py\"",
            "timeout": 10,
            "statusMessage": "Syncing PowerContext"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "powercontext": {
      "type": "http",
      "url": "${POWERCONTEXT_WORKBUDDY_SERVER_URL:-http://127.0.0.1:8000}/mcp",
      "headers": {
        "Authorization": "${POWERCONTEXT_WORKBUDDY_AUTHORIZATION:-}"
      },
      "description": "PowerContext agent memory & handoff MCP server (local service on port 8000)"
    }
  }
}

mkdir -p ~/.workbuddy/skills
cp -R integrations/workbuddy/plugins/powercontext/skills/project-context \
  ~/.workbuddy/skills/
cat > ~/.workbuddy/skills/project-context/.powercontext.json <<'EOF'
{"schema": 1, "owner": "powercontext", "integration": "workbuddy"}
EOF

powercontext server run

powercontext doctor

Configuration

The hook uses http://127.0.0.1:8000 by default. Environment variables override the defaults; restart WorkBuddy after changing them.

The hook validates its PowerContext MCP URL and derives the HTTP API base by removing the final /mcp path segment. Change plugins/powercontext/.mcp.json before installing when the loopback default is not appropriate. MCP URLs cannot contain credentials, query strings, or fragments; plain HTTP is accepted only for loopback hosts.

Runtime behavior

• Recall calls POST /v1/context/prepare once per prompt, requests an 8000-byte total budget, strictly validates powercontext.prepared-context.v1, and injects the returned content unchanged as untrusted history.
• Capture independently posts the prompt to POST /v1/sources/content with stable, content-addressed source_id values.
• Recall, capture, and flush fail independently. An unavailable Server never blocks normal WorkBuddy work.
• For an empty result, authentication failure, version mismatch, unavailable Server, or invalid response, the hook writes one diagnostic JSON line to stderr. Diagnostics contain status and byte counts only—never the query, scope, content, citation, response body, or authorization value.

Authentication

Optional local bearer authentication uses POWERCONTEXT_WORKBUDDY_AUTHORIZATION, whose value must be a complete Bearer <token> header. .mcp.json stores only an environment-variable template for the Authorization value; WorkBuddy expands it from the environment, and the hook reads the same variable. Missing or empty values preserve the default unauthenticated flow. Never put the token itself in .mcp.json or the Server URL.

Manual uninstallation

1. Remove the UserPromptSubmit PowerContext entry from ~/.workbuddy/settings.json.
2. Remove the powercontext entry from ~/.workbuddy/mcp.json.
3. Remove the hook files and the scope resolver from <WORKBUDDY_HOOKS_DIR>.
4. Remove ~/.workbuddy/skills/project-context.
5. Optionally stop the Server and delete its local data directory.