From 803bc1728671f576b0bd2700cc52cf37da114aa2 Mon Sep 17 00:00:00 2001 From: "xuyan.wxy" Date: Sun, 14 Jun 2026 17:01:25 +0800 Subject: [PATCH 1/2] Add Codex CLI plugin support --- .claude-plugin/marketplace.json | 6 +- apps/README.md | 14 +- .../.claude-plugin/marketplace.json | 6 +- .../.codex-plugin/plugin.json | 30 +++++ apps/claude-code-plugin/README.md | 47 ++++++- apps/claude-code-plugin/SETUP.md | 72 +++++++---- .../scripts/package-plugin.sh | 1 + apps/claude-code-plugin/skills/init/SKILL.md | 8 +- .../claude-code-plugin/skills/recall/SKILL.md | 1 + .../skills/remember/SKILL.md | 1 + apps/claude-code-plugin/skills/reset/SKILL.md | 7 +- .../claude-code-plugin/skills/status/SKILL.md | 10 +- apps/claude-code-plugin/skills/stop/SKILL.md | 8 +- docs/integrations/codex.md | 120 +++++++++++++----- docs/integrations/overview.md | 5 +- 15 files changed, 252 insertions(+), 84 deletions(-) create mode 100644 apps/claude-code-plugin/.codex-plugin/plugin.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7f8f89361..522babc20 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,16 +5,16 @@ "email": "open_oceanbase@oceanbase.com" }, "metadata": { - "description": "PowerMem marketplace: intelligent memory for Claude Code.", + "description": "PowerMem marketplace: intelligent memory for Claude Code and Codex CLI.", "version": "0.1.0" }, "plugins": [ { "name": "memory-powermem", "source": "./apps/claude-code-plugin", - "description": "PowerMem intelligent memory for Claude Code: auto-recall on prompt submit and auto-save on session end via HTTP hooks.", + "description": "PowerMem intelligent memory for Claude Code and Codex CLI: Claude Code uses HTTP hooks; Codex CLI uses skills with explicit MCP wiring.", "category": "memory", - "tags": ["memory", "powermem", "rag", "hooks", "oceanbase"] + "tags": ["memory", "powermem", "rag", "hooks", "mcp", "codex", "oceanbase"] } ] } diff --git a/apps/README.md b/apps/README.md index 832a10980..dfde7caaf 100644 --- a/apps/README.md +++ b/apps/README.md @@ -7,10 +7,14 @@ First-party setup flows that connect PowerMem to AI clients and IDEs. Every path | If you use… | Use this directory | One-line agent prompt | |-------------|-------------------|------------------------| | **Cursor**, **VS Code**, **Windsurf**, **GitHub Copilot**, **Qoder** | [`vscode-extension/`](vscode-extension/) | `Read and follow apps/vscode-extension/SETUP.md to setup PowerMem` | -| **Claude Desktop**, **Cline**, **Codex**, **OpenCode**, Roo Code, Goose, or any other MCP client | [`mcp-client/`](mcp-client/) | `Read and follow apps/mcp-client/SETUP.md to setup PowerMem` | +| **Claude Desktop**, **Cline**, **OpenCode**, Roo Code, Goose, or any other MCP client | [`mcp-client/`](mcp-client/) | `Read and follow apps/mcp-client/SETUP.md to setup PowerMem` | +| **Codex CLI** | [`claude-code-plugin/`](claude-code-plugin/) | Install `memory-powermem` with `codex plugin`, then ask Codex to use the init skill. | | **Claude Code** (hook-based plugin) | [`claude-code-plugin/`](claude-code-plugin/) | `Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code.` | -> **Codex** and **OpenCode** belong under `mcp-client/`, not `vscode-extension/`. The VS Code extension flow is for VS Code–compatible IDEs only. +> **Codex CLI** has a native plugin path under `claude-code-plugin/`; generic +> MCP-only Codex setup can still use `mcp-client/`. **OpenCode** belongs under +> `mcp-client/`, not `vscode-extension/`. The VS Code extension flow is for +> VS Code–compatible IDEs only. For **OpenClaw**, use the separate [`memory-powermem`](https://github.com/ob-labs/memory-powermem) plugin — see [OpenClaw integration](../docs/integrations/openclaw.md). @@ -19,8 +23,8 @@ For **OpenClaw**, use the separate [`memory-powermem`](https://github.com/ob-lab | Directory | Description | |-----------|-------------| | **[vscode-extension](vscode-extension/)** | VS Code extension and agent-guided setup for Cursor, VS Code, Windsurf, GitHub Copilot, and Qoder. Commands: Query memories, Add selection, Quick note, Link to AI tools, Setup, Dashboard. | -| **[mcp-client](mcp-client/)** | Agent-guided setup for generic MCP clients (Claude Desktop, Cline, Codex, OpenCode, and others). Uses `powermem-mcp` directly; prefers SSE on port `8848`. | -| **[claude-code-plugin](claude-code-plugin/)** | Claude Code plugin with **HTTP mode by default** (REST hooks; empty `mcpServers`). Optional **MCP mode** via [`config/mcp-mode.mcp.json`](claude-code-plugin/config/mcp-mode.mcp.json). | +| **[mcp-client](mcp-client/)** | Agent-guided setup for generic MCP clients (Claude Desktop, Cline, OpenCode, and others). Uses `powermem-mcp` directly; prefers SSE on port `8848`. | +| **[claude-code-plugin](claude-code-plugin/)** | Claude Code and Codex CLI plugin descriptors. Claude Code uses **HTTP mode by default** (REST hooks; empty `mcpServers`). Codex CLI uses skills plus explicit `codex mcp add`. Optional Claude **MCP mode** via [`config/mcp-mode.mcp.json`](claude-code-plugin/config/mcp-mode.mcp.json). | ## Quick start @@ -52,7 +56,7 @@ All setup flows share the same backend priority: 3. **Fall back** to MCP-only only when HTTP is unavailable: `powermem-mcp sse 8848` (or streamable HTTP / stdio when the target client requires it) -The `mcp-client/` path uses `powermem-mcp` directly and prefers SSE on port `8848`. The `vscode-extension/` path prefers the HTTP API and links the current IDE/client first. The `claude-code-plugin/` path defaults to HTTP hooks and optionally enables in-chat MCP tools. +The `mcp-client/` path uses `powermem-mcp` directly and prefers SSE on port `8848`. The `vscode-extension/` path prefers the HTTP API and links the current IDE/client first. The `claude-code-plugin/` path defaults to HTTP hooks for Claude Code, and provides a Codex CLI plugin that manages init/status/stop/reset skills while MCP is added explicitly with `codex mcp add`. ## Setup & uninstall guides diff --git a/apps/claude-code-plugin/.claude-plugin/marketplace.json b/apps/claude-code-plugin/.claude-plugin/marketplace.json index db203b4cc..edc7a2611 100644 --- a/apps/claude-code-plugin/.claude-plugin/marketplace.json +++ b/apps/claude-code-plugin/.claude-plugin/marketplace.json @@ -5,16 +5,16 @@ "email": "open_oceanbase@oceanbase.com" }, "metadata": { - "description": "PowerMem marketplace: intelligent memory for Claude Code (Ebbinghaus decay, multi-agent, HTTP hooks).", + "description": "PowerMem marketplace: intelligent memory for Claude Code and Codex CLI.", "version": "0.1.0" }, "plugins": [ { "name": "memory-powermem", "source": "./", - "description": "PowerMem intelligent memory for Claude Code: auto-recall on prompt submit and auto-save on session end via HTTP hooks. Ebbinghaus decay and multi-agent support.", + "description": "PowerMem intelligent memory for Claude Code and Codex CLI: Claude Code uses HTTP hooks; Codex CLI uses skills with explicit MCP wiring.", "category": "memory", - "tags": ["memory", "powermem", "rag", "hooks", "oceanbase"] + "tags": ["memory", "powermem", "rag", "hooks", "mcp", "codex", "oceanbase"] } ] } diff --git a/apps/claude-code-plugin/.codex-plugin/plugin.json b/apps/claude-code-plugin/.codex-plugin/plugin.json new file mode 100644 index 000000000..589f67bf1 --- /dev/null +++ b/apps/claude-code-plugin/.codex-plugin/plugin.json @@ -0,0 +1,30 @@ +{ + "name": "memory-powermem", + "version": "0.1.0", + "description": "PowerMem intelligent memory for Codex CLI: initialize a local PowerMem backend and use memory skills with optional MCP tools.", + "author": { + "name": "OceanBase / PowerMem", + "email": "open_oceanbase@oceanbase.com", + "url": "https://github.com/oceanbase" + }, + "homepage": "https://github.com/oceanbase/powermem/tree/main/apps/claude-code-plugin", + "repository": "https://github.com/oceanbase/powermem", + "license": "Apache-2.0", + "keywords": ["memory", "powermem", "codex", "mcp", "oceanbase"], + "skills": "./skills/", + "interface": { + "displayName": "PowerMem", + "shortDescription": "Persistent memory for Codex CLI.", + "longDescription": "Initialize and connect a local PowerMem backend for persistent recall, memory writes, and project decisions from Codex CLI.", + "developerName": "OceanBase / PowerMem", + "category": "Developer Tools", + "capabilities": ["Interactive", "Read", "Write"], + "websiteURL": "https://github.com/oceanbase/powermem", + "defaultPrompt": [ + "Initialize PowerMem for Codex CLI.", + "Search my PowerMem memories for this task.", + "Remember this project decision in PowerMem." + ], + "brandColor": "#2563EB" + } +} diff --git a/apps/claude-code-plugin/README.md b/apps/claude-code-plugin/README.md index d6b0195e5..9dabfb8dd 100644 --- a/apps/claude-code-plugin/README.md +++ b/apps/claude-code-plugin/README.md @@ -1,19 +1,24 @@ -# PowerMem Plugin for Claude Code +# PowerMem Plugin for Claude Code and Codex CLI The full Claude Code integration guide — the auto-setup prompt, manual steps, the two connection modes (HTTP / MCP), hooks, configuration, troubleshooting, and -uninstall — now lives in the docs and is the single source of truth: +uninstall — lives in the docs: **➡ [docs/integrations/claude_code.md](../../docs/integrations/claude_code.md)** -This directory still contains the plugin itself (`.claude-plugin/`, `hooks/`, -`skills/`, `config/`, `.mcp.json`). To load it: +The Codex CLI guide lives here: + +**➡ [docs/integrations/codex.md](../../docs/integrations/codex.md)** + +This directory contains the plugin descriptors and shared runtime files +(`.claude-plugin/`, `.codex-plugin/`, `hooks/`, `skills/`, `config/`, `.mcp.json`). +To load it directly in Claude Code: ```bash claude --plugin-dir /path/to/powermem/apps/claude-code-plugin ``` -## Marketplace install +## Claude Code Marketplace Install Once the PowerMem marketplace entry is available, install the Claude Code plugin with: @@ -53,6 +58,38 @@ branch: /reload-plugins ``` +## Codex CLI Install + +Install the Codex marketplace and plugin: + +```bash +codex plugin marketplace add oceanbase/powermem +codex plugin add memory-powermem@powermem +``` + +For branch testing: + +```bash +codex plugin remove memory-powermem 2>/dev/null || true +codex plugin marketplace remove powermem 2>/dev/null || true +codex plugin marketplace add https://github.com//powermem.git --ref +codex plugin add memory-powermem@powermem +``` + +Start a new Codex thread, then ask Codex: + +```text +Use the memory-powermem init skill to initialize PowerMem. +``` + +After init succeeds, wire MCP to the managed server: + +```bash +. "$HOME/.powermem/runtime.env" +codex mcp remove powermem 2>/dev/null || true +codex mcp add powermem --url "${POWERMEM_BASE_URL%/}/mcp" +``` + To pre-download the default local embedding model through ModelScope before starting the server: diff --git a/apps/claude-code-plugin/SETUP.md b/apps/claude-code-plugin/SETUP.md index efb95566d..c680ba39d 100644 --- a/apps/claude-code-plugin/SETUP.md +++ b/apps/claude-code-plugin/SETUP.md @@ -1,4 +1,4 @@ -# PowerMem — automated Claude Code setup +# PowerMem — automated Claude Code and Codex CLI setup This file is a **prompt for Claude Code**. Open Claude Code in your terminal and say: @@ -9,12 +9,15 @@ source tree or not, ask you for the few required secrets, and wire PowerMem up a **globally enabled** plugin so every `claude` session (interactive AND non-interactive `claude -p`) uses it automatically — no per-session `--plugin-dir` flag. +The **Installed plugin initialization** section is shared by Claude Code and +Codex CLI. The later source/developer setup flow is Claude Code specific. + --- ## Installed plugin initialization Use this section when the `memory-powermem` plugin is already installed from a -Claude Code marketplace and the user runs: +Claude Code or Codex marketplace and the user runs the PowerMem init skill: ```text /memory-powermem:init @@ -22,9 +25,10 @@ Claude Code marketplace and the user runs: In this mode, **do not** run the source/developer install flow below: do not build hook binaries, do not stage the plugin, do not run `claude plugin marketplace add`, -do not run `claude plugin install`, and do not build the dashboard. The plugin is -already installed; this section only prepares the PowerMem backend that the plugin -connects to. +do not run `claude plugin install`, do not run `codex plugin marketplace add`, do +not run `codex plugin add`, and do not build the dashboard. The plugin is already +installed; this section only prepares the PowerMem backend that the plugin connects +to. Installed-plugin init creates a plugin-local Python environment and installs the backend package with `pip install powermem` by default. Therefore the PyPI release @@ -47,26 +51,47 @@ $HOME/.powermem/ Follow these steps: -**Always use a two-step invocation: discover or reuse `CLAUDE_PLUGIN_ROOT` -first, then run the script.** Never write `VAR=val sh "$VAR/..."` on one line — +**Always use a two-step invocation: discover or reuse `PLUGIN_ROOT` first, then +run the script.** Never write `VAR=val sh "$VAR/..."` on one line — the shell expands `$VAR` before the assignment, producing an empty path. ```bash -# If CLAUDE_PLUGIN_ROOT is not already set, find the plugin root: -if [ -z "${CLAUDE_PLUGIN_ROOT:-}" ]; then - export CLAUDE_PLUGIN_ROOT=$(find ~/.claude/plugins/cache/powermem/memory-powermem -maxdepth 2 -name scripts -type d 2>/dev/null | head -1 | xargs dirname) +# If PLUGIN_ROOT is not already set, reuse the host-provided root if available. +if [ -z "${PLUGIN_ROOT:-}" ]; then + PLUGIN_ROOT="${POWERMEM_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-}}}" +fi + +# If no root variable is available, find the installed plugin copy. +if [ -z "${PLUGIN_ROOT:-}" ]; then + PLUGIN_ROOT=$( + find "$HOME/.claude/plugins" "$HOME/.codex/plugins" \ + -maxdepth 8 -type d -name scripts 2>/dev/null | + while IFS= read -r scripts_dir; do + case "$scripts_dir" in + *memory-powermem*) dirname "$scripts_dir"; break ;; + esac + done + ) fi -sh "$CLAUDE_PLUGIN_ROOT/scripts/..." + +[ -n "${PLUGIN_ROOT:-}" ] || { + echo "PowerMem plugin root not found. Reinstall memory-powermem and retry." + exit 1 +} + +sh "$PLUGIN_ROOT/scripts/..." ``` 1. If the skill was just installed or updated, ask the user to run `/reload-plugins` - first, then retry `/memory-powermem:init`. -2. Run `sh "$CLAUDE_PLUGIN_ROOT/scripts/status.sh"` and inspect whether config, - venv, managed PID, Python versions, and health are present. + first in Claude Code, then retry `/memory-powermem:init`. In Codex CLI, start + a new thread after installing or updating the plugin so Codex loads the updated + skills. +2. Run `sh "$PLUGIN_ROOT/scripts/status.sh"` and inspect whether config, venv, + managed PID, Python versions, and health are present. 3. If `.env` is missing, run init with auto-detection first: ```bash - sh "$CLAUDE_PLUGIN_ROOT/scripts/init.sh" + sh "$PLUGIN_ROOT/scripts/init.sh" ``` The script reads the current process environment first and attempts to derive @@ -85,7 +110,7 @@ sh "$CLAUDE_PLUGIN_ROOT/scripts/..." POWERMEM_INIT_LLM_PROVIDER=anthropic \ POWERMEM_INIT_LLM_MODEL=anthropic/claude-sonnet-4.6 \ POWERMEM_INIT_LLM_API_KEY=... \ - sh "$CLAUDE_PLUGIN_ROOT/scripts/init.sh" + sh "$PLUGIN_ROOT/scripts/init.sh" ``` For a bearer-token gateway, use: @@ -95,7 +120,7 @@ sh "$CLAUDE_PLUGIN_ROOT/scripts/..." POWERMEM_INIT_LLM_MODEL=anthropic/claude-sonnet-4.6 \ POWERMEM_INIT_LLM_AUTH_TOKEN=... \ POWERMEM_INIT_LLM_BASE_URL=https://your-gateway.example.com \ - sh "$CLAUDE_PLUGIN_ROOT/scripts/init.sh" + sh "$PLUGIN_ROOT/scripts/init.sh" ``` Optional variables: @@ -109,10 +134,11 @@ sh "$CLAUDE_PLUGIN_ROOT/scripts/..." `all-MiniLM-L6-v2` embedding model before starting the server. 5. Never print API keys, auth tokens, or other credentials. Mask any secret in summaries. -6. After init succeeds, run `sh "$CLAUDE_PLUGIN_ROOT/scripts/status.sh"` again and +6. After init succeeds, run `sh "$PLUGIN_ROOT/scripts/status.sh"` again and report the base URL. -7. The hook launcher reads `runtime.env`, so once init writes a base URL, prompt - recall and session-save hooks use that backend automatically. +7. Claude Code hooks read `runtime.env`, so once init writes a base URL, prompt + recall and session-save hooks use that backend automatically. Codex CLI should + use the same base URL when adding the MCP server with `codex mcp add`. Model preload branches on region (same as source setup — detect with Step 1a): @@ -646,12 +672,12 @@ make build-claude-hook #### [E005] Storage Backend Initialization **Problem**: 503 errors on API calls despite server health -**Fix**: the Claude Code plugin defaults to embedded OceanBase/seekdb. Stop the +**Fix**: the PowerMem plugin defaults to embedded OceanBase/seekdb. Stop the managed server, remove stale seekdb data, and restart init: ```bash -sh "$CLAUDE_PLUGIN_ROOT/scripts/stop.sh" +sh "$PLUGIN_ROOT/scripts/stop.sh" rm -rf "$HOME/.powermem/seekdb_data" -sh "$CLAUDE_PLUGIN_ROOT/scripts/init.sh" +sh "$PLUGIN_ROOT/scripts/init.sh" ``` #### [E006] Model Download Timeout diff --git a/apps/claude-code-plugin/scripts/package-plugin.sh b/apps/claude-code-plugin/scripts/package-plugin.sh index df87169ea..9e988c85d 100755 --- a/apps/claude-code-plugin/scripts/package-plugin.sh +++ b/apps/claude-code-plugin/scripts/package-plugin.sh @@ -27,6 +27,7 @@ STAGE="${TMP}/powermem-claude-code-plugin" mkdir -p "${STAGE}" cp -R "${PLUGIN_ROOT}/.claude-plugin" "${STAGE}/" +[[ -d "${PLUGIN_ROOT}/.codex-plugin" ]] && cp -R "${PLUGIN_ROOT}/.codex-plugin" "${STAGE}/" cp "${PLUGIN_ROOT}/.mcp.json" "${STAGE}/" [[ -d "${PLUGIN_ROOT}/config" ]] && cp -R "${PLUGIN_ROOT}/config" "${STAGE}/" cp -R "${PLUGIN_ROOT}/hooks" "${STAGE}/" diff --git a/apps/claude-code-plugin/skills/init/SKILL.md b/apps/claude-code-plugin/skills/init/SKILL.md index eaff32e72..cdc243aa9 100644 --- a/apps/claude-code-plugin/skills/init/SKILL.md +++ b/apps/claude-code-plugin/skills/init/SKILL.md @@ -1,15 +1,17 @@ --- -description: Initialize PowerMem for Claude Code after the plugin is installed. Use when the user asks to set up, initialize, or repair PowerMem. +name: init +description: Initialize PowerMem for Claude Code or Codex CLI after the plugin is installed. Use when the user asks to set up, initialize, or repair PowerMem. --- -Initialize PowerMem for Claude Code. +Initialize PowerMem for Claude Code or Codex CLI. Read `apps/claude-code-plugin/SETUP.md`, section "Installed plugin initialization", and follow only that section. Do not run the source/developer setup flow from `SETUP.md`: do not build hook binaries, do not stage the plugin, do not run `claude plugin marketplace add`, do -not run `claude plugin install`, and do not build the dashboard. +not run `claude plugin install`, do not run `codex plugin marketplace add`, do +not run `codex plugin add`, and do not build the dashboard. Use the plugin scripts as directed by that section: diff --git a/apps/claude-code-plugin/skills/recall/SKILL.md b/apps/claude-code-plugin/skills/recall/SKILL.md index 0ecdffba4..5deeece87 100644 --- a/apps/claude-code-plugin/skills/recall/SKILL.md +++ b/apps/claude-code-plugin/skills/recall/SKILL.md @@ -1,4 +1,5 @@ --- +name: recall description: Search PowerMem for relevant memories. Use before answering questions about the user, project, or past decisions. --- diff --git a/apps/claude-code-plugin/skills/remember/SKILL.md b/apps/claude-code-plugin/skills/remember/SKILL.md index 35246f046..e2bcf1623 100644 --- a/apps/claude-code-plugin/skills/remember/SKILL.md +++ b/apps/claude-code-plugin/skills/remember/SKILL.md @@ -1,4 +1,5 @@ --- +name: remember description: Add or update a memory in PowerMem. Use when the user or conversation reveals a fact, preference, or decision that should be remembered across sessions. --- diff --git a/apps/claude-code-plugin/skills/reset/SKILL.md b/apps/claude-code-plugin/skills/reset/SKILL.md index d6b79ce35..583ae7a23 100644 --- a/apps/claude-code-plugin/skills/reset/SKILL.md +++ b/apps/claude-code-plugin/skills/reset/SKILL.md @@ -1,9 +1,14 @@ --- +name: reset description: Reset PowerMem plugin-local data after explicit user confirmation. --- Reset is destructive. First tell the user it will stop the plugin-managed server and delete the plugin data directory containing `.env`, runtime state, logs, and venv. Only after explicit confirmation, run: -`POWERMEM_RESET_CONFIRM=delete sh "${CLAUDE_PLUGIN_ROOT}/scripts/reset.sh"` +`POWERMEM_RESET_CONFIRM=delete sh "$PLUGIN_ROOT/scripts/reset.sh"` + +Resolve `PLUGIN_ROOT` from `$POWERMEM_PLUGIN_ROOT`, `$CLAUDE_PLUGIN_ROOT`, or +`$CODEX_PLUGIN_ROOT` first. If none is set, find the installed plugin root under +`~/.claude/plugins` or `~/.codex/plugins`. Do not delete project files or unrelated PowerMem servers. diff --git a/apps/claude-code-plugin/skills/status/SKILL.md b/apps/claude-code-plugin/skills/status/SKILL.md index b6f94ea10..01a1bd192 100644 --- a/apps/claude-code-plugin/skills/status/SKILL.md +++ b/apps/claude-code-plugin/skills/status/SKILL.md @@ -1,6 +1,10 @@ --- -description: Check whether PowerMem is configured, running, and reachable from Claude Code. +name: status +description: Check whether PowerMem is configured, running, and reachable from Claude Code or Codex CLI. --- -Run `sh "${CLAUDE_PLUGIN_ROOT}/scripts/status.sh"` when available. Report the data directory, base URL, managed server PID if any, and health state. Do not print `.env` contents. - +Resolve the PowerMem plugin root first, then run `sh "$PLUGIN_ROOT/scripts/status.sh"`. +Use `$POWERMEM_PLUGIN_ROOT`, `$CLAUDE_PLUGIN_ROOT`, or `$CODEX_PLUGIN_ROOT` when +available; otherwise find the installed plugin root under `~/.claude/plugins` or +`~/.codex/plugins`. Report the data directory, base URL, managed server PID if +any, and health state. Do not print `.env` contents. diff --git a/apps/claude-code-plugin/skills/stop/SKILL.md b/apps/claude-code-plugin/skills/stop/SKILL.md index f4ebab7e2..b6d9758e3 100644 --- a/apps/claude-code-plugin/skills/stop/SKILL.md +++ b/apps/claude-code-plugin/skills/stop/SKILL.md @@ -1,6 +1,8 @@ --- -description: Stop the PowerMem server started by the Claude Code plugin. +name: stop +description: Stop the PowerMem server started by the PowerMem plugin. --- -Run `sh "${CLAUDE_PLUGIN_ROOT}/scripts/stop.sh"` when available. This stops only the server PID tracked in the plugin data directory. Do not kill unrelated PowerMem processes unless the user explicitly asks. - +Resolve the PowerMem plugin root first, then run `sh "$PLUGIN_ROOT/scripts/stop.sh"`. +This stops only the server PID tracked in the plugin data directory. Do not kill +unrelated PowerMem processes unless the user explicitly asks. diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md index 0142f8248..cfc3a40f6 100644 --- a/docs/integrations/codex.md +++ b/docs/integrations/codex.md @@ -1,63 +1,115 @@ -# Codex +# Codex CLI -Connect Codex to PowerMem through MCP. The recommended setup path is the generic [PowerMem MCP client setup](https://github.com/oceanbase/powermem/blob/main/apps/mcp-client/SETUP.md). +Connect Codex CLI to PowerMem with the native `memory-powermem` plugin plus an +explicit MCP server entry. -## Recommended setup — let your MCP client agent set it up +The Codex plugin installs PowerMem skills and reuses the same backend bootstrap +as the Claude Code plugin. It intentionally does **not** register Codex hooks or +write a hard-coded MCP URL during plugin install. After init writes +`~/.powermem/runtime.env`, add the MCP endpoint with `codex mcp add`. -First download the code and enter the directory: +## Recommended Setup + +Install the PowerMem marketplace and plugin: + +```bash +codex plugin marketplace add oceanbase/powermem +codex plugin add memory-powermem@powermem +``` + +For branch testing from a fork: ```bash -git clone https://github.com/oceanbase/powermem -cd powermem +codex plugin remove memory-powermem 2>/dev/null || true +codex plugin marketplace remove powermem 2>/dev/null || true +codex plugin marketplace add https://github.com//powermem.git --ref +codex plugin add memory-powermem@powermem ``` -Then open the AI agent window where you run Codex and paste this one line: +Start a new Codex thread after installing or updating the plugin so Codex loads +the new skills. Then ask Codex: ```text -Read and follow apps/mcp-client/SETUP.md to setup PowerMem +Use the memory-powermem init skill to initialize PowerMem. ``` -The agent follows [`apps/mcp-client/SETUP.md`](https://github.com/oceanbase/powermem/blob/main/apps/mcp-client/SETUP.md), runs `powermem-mcp` directly, and updates only the Codex MCP configuration. +The init skill prepares shared local state under `~/.powermem/`: -## Prerequisites +```text +~/.powermem/.env +~/.powermem/runtime.env +~/.powermem/powermem.pid +~/.powermem/powermem-server.log +~/.powermem/venv/ +``` -- Codex installed and able to read `~/.codex/context.json`. -- A running PowerMem MCP endpoint or local `powermem-mcp` command. -- PowerMem configured with your LLM provider, API key, and model. +After init succeeds, wire Codex MCP to the managed server: -## Manual setup +```bash +. "$HOME/.powermem/runtime.env" +codex mcp remove powermem 2>/dev/null || true +codex mcp add powermem --url "${POWERMEM_BASE_URL%/}/mcp" +``` -Use this section only when you want to wire Codex by hand. +## Prerequisites -### Configure +- Codex CLI with `codex plugin` and `codex mcp` commands. +- A supported Python runtime for the PowerMem backend. The init script creates + `~/.powermem/venv` and installs `powermem` there. +- Anthropic credentials available from the environment or `~/.claude/settings.json`. + `ANTHROPIC_API_KEY` works by itself. `ANTHROPIC_AUTH_TOKEN` must be paired with + `ANTHROPIC_BASE_URL`. -Add PowerMem to `~/.codex/context.json`: +## Manual MCP Only -```json -{ - "mcpServers": { - "powermem": { - "url": "http://localhost:8848/mcp" - } - } -} +If you do not want the Codex plugin skills, you can still connect Codex as a +plain MCP client: + +```bash +codex mcp add powermem --url http://localhost:8848/mcp ``` -If the PowerMem MCP endpoint requires auth, add the matching header or pass -`POWERMEM_API_KEY` to a stdio MCP command. +Use this only when a PowerMem HTTP server is already running. The native plugin +path is preferred because the `init`, `status`, `stop`, and `reset` skills manage +the local server lifecycle for you. ## Verify -1. Restart Codex so it reloads `~/.codex/context.json`. -2. Confirm the `powermem` MCP server is listed. -3. Add a probe memory with content `PowerMem Codex probe: dragonfruit-zx9`. -4. Search for `dragonfruit-zx9` and confirm Codex receives the result. +1. Confirm the managed server is healthy: + + ```bash + . "$HOME/.powermem/runtime.env" + curl -fsS "${POWERMEM_BASE_URL%/}/api/v1/system/health" + ``` + +2. Confirm Codex has the MCP entry: + + ```bash + codex mcp list + ``` + +3. In Codex, ask it to remember a probe such as + `PowerMem Codex probe: dragonfruit-zx9`, then search for `dragonfruit-zx9`. ## Troubleshooting -- If Codex ignores the config, validate that `~/.codex/context.json` is valid JSON. -- If MCP fails, confirm `http://localhost:8848/mcp` is reachable or switch to stdio MCP. +- If the plugin skills do not appear, start a new Codex thread after + `codex plugin add`. +- If MCP uses the wrong port, reload `~/.powermem/runtime.env` and re-run + `codex mcp remove powermem` followed by `codex mcp add`. +- If the server fails to start, read `~/.powermem/powermem-server.log`. +- If package installation is slow in CN networks, init detects the current + machine region and adds the Tsinghua PyPI mirror for `pip install`. ## Uninstall -Remove `mcpServers.powermem` from `~/.codex/context.json`. Leave other providers untouched. For agent-guided cleanup, follow [`apps/mcp-client/UNINSTALL.md`](https://github.com/oceanbase/powermem/blob/main/apps/mcp-client/UNINSTALL.md). +Remove the MCP entry and plugin: + +```bash +codex mcp remove powermem +codex plugin remove memory-powermem 2>/dev/null || true +``` + +If your Codex CLI does not expose `plugin remove`, use `codex plugin list` to +inspect the installed plugin and remove it through the CLI version's supported +plugin management command. diff --git a/docs/integrations/overview.md b/docs/integrations/overview.md index a2e1ba487..e934bbbf4 100644 --- a/docs/integrations/overview.md +++ b/docs/integrations/overview.md @@ -9,6 +9,9 @@ the local `pmem` CLI) — there are no per-client schema rewrites. - **[Claude Code](./claude_code.md)** — Plugin (`memory-powermem`) with silent HTTP-mode capture via hooks and an optional MCP mode for in-chat `search_memories` / `add_memory` tools. +- **[Codex CLI](./codex.md)** — Native `memory-powermem` plugin with + init/status/stop/reset skills and explicit `codex mcp add` wiring to the + managed PowerMem server. - **[VS Code](./vs_code.md)** — First-party extension with setup UI, status bar, query/add commands, dashboard, and AI-tool config linking. - **[Cursor](./cursor.md)** — MCP setup through the VS Code extension, writing @@ -22,7 +25,7 @@ the local `pmem` CLI) — there are no per-client schema rewrites. and optional HTTP backend mode. - **[Cline](./cline.md)** — Standard MCP setup for Cline. - **[Generic MCP client](./mcp_client.md)** — Stdio, streamable HTTP, and SSE - setup for Claude Desktop, Cline, Codex, OpenCode, Roo Code, Goose, and other MCP clients. + setup for Claude Desktop, Cline, OpenCode, Roo Code, Goose, and other MCP clients. ## Frameworks & SDKs From 449da79437b1c7cdff8bfeb13ea2237e49a029f6 Mon Sep 17 00:00:00 2001 From: "xuyan.wxy" Date: Sun, 14 Jun 2026 17:16:52 +0800 Subject: [PATCH 2/2] Rename shared agent plugin directory --- .claude-plugin/marketplace.json | 2 +- .github/workflows/plugins-build.yml | 24 ++++---- Makefile | 12 ++-- README.md | 4 +- README_CN.md | 4 +- README_JP.md | 4 +- apps/README.md | 12 ++-- .../.claude-plugin/marketplace.json | 0 .../.claude-plugin/plugin.json | 0 .../.codex-plugin/plugin.json | 2 +- .../.gitignore | 0 .../.mcp.json | 0 .../CHANGELOG.md | 2 +- .../README.md | 2 +- .../SETUP.md | 12 ++-- .../UNINSTALL.md | 8 +-- .../cmd/powermem-hook/detach_unix.go | 0 .../cmd/powermem-hook/detach_windows.go | 0 .../cmd/powermem-hook/main.go | 0 .../cmd/powermem-hook/poll.go | 0 .../config/README.md | 0 .../config/http-mode.mcp.json | 0 .../config/mcp-mode.mcp.json | 0 .../go.mod | 0 .../hooks/bin/powermem-hook-darwin-amd64 | Bin .../hooks/bin/powermem-hook-darwin-arm64 | Bin .../hooks/bin/powermem-hook-linux-amd64 | Bin .../hooks/bin/powermem-hook-linux-arm64 | Bin .../hooks/bin/powermem-hook-windows-amd64.exe | Bin .../hooks/hooks.json | 0 .../hooks/hooks.windows.example.json | 0 .../hooks/run-hook.ps1 | 0 .../hooks/run-hook.sh | 0 .../init-flow.png | Bin .../init-flow.svg | 0 .../scripts/apply-connection-mode.sh | 0 .../scripts/build-hook-binaries.sh | 0 .../scripts/common.sh | 0 .../scripts/init.sh | 4 +- .../scripts/package-plugin.sh | 10 ++-- .../scripts/preload-model.sh | 0 .../scripts/reset.sh | 0 .../scripts/status.sh | 2 +- .../scripts/stop.sh | 0 .../skills/init/SKILL.md | 2 +- .../skills/recall/SKILL.md | 0 .../skills/remember/SKILL.md | 0 .../skills/reset/SKILL.md | 0 .../skills/status/SKILL.md | 0 .../skills/stop/SKILL.md | 0 .../watcher/README.md | 0 docs/integrations/claude_code.md | 54 +++++++++--------- 52 files changed, 81 insertions(+), 79 deletions(-) rename apps/{claude-code-plugin => agent-plugin}/.claude-plugin/marketplace.json (100%) rename apps/{claude-code-plugin => agent-plugin}/.claude-plugin/plugin.json (100%) rename apps/{claude-code-plugin => agent-plugin}/.codex-plugin/plugin.json (98%) rename apps/{claude-code-plugin => agent-plugin}/.gitignore (100%) rename apps/{claude-code-plugin => agent-plugin}/.mcp.json (100%) rename apps/{claude-code-plugin => agent-plugin}/CHANGELOG.md (91%) rename apps/{claude-code-plugin => agent-plugin}/README.md (98%) rename apps/{claude-code-plugin => agent-plugin}/SETUP.md (98%) rename apps/{claude-code-plugin => agent-plugin}/UNINSTALL.md (94%) rename apps/{claude-code-plugin => agent-plugin}/cmd/powermem-hook/detach_unix.go (100%) rename apps/{claude-code-plugin => agent-plugin}/cmd/powermem-hook/detach_windows.go (100%) rename apps/{claude-code-plugin => agent-plugin}/cmd/powermem-hook/main.go (100%) rename apps/{claude-code-plugin => agent-plugin}/cmd/powermem-hook/poll.go (100%) rename apps/{claude-code-plugin => agent-plugin}/config/README.md (100%) rename apps/{claude-code-plugin => agent-plugin}/config/http-mode.mcp.json (100%) rename apps/{claude-code-plugin => agent-plugin}/config/mcp-mode.mcp.json (100%) rename apps/{claude-code-plugin => agent-plugin}/go.mod (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/bin/powermem-hook-darwin-amd64 (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/bin/powermem-hook-darwin-arm64 (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/bin/powermem-hook-linux-amd64 (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/bin/powermem-hook-linux-arm64 (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/bin/powermem-hook-windows-amd64.exe (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/hooks.json (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/hooks.windows.example.json (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/run-hook.ps1 (100%) rename apps/{claude-code-plugin => agent-plugin}/hooks/run-hook.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/init-flow.png (100%) rename apps/{claude-code-plugin => agent-plugin}/init-flow.svg (100%) rename apps/{claude-code-plugin => agent-plugin}/scripts/apply-connection-mode.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/scripts/build-hook-binaries.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/scripts/common.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/scripts/init.sh (99%) rename apps/{claude-code-plugin => agent-plugin}/scripts/package-plugin.sh (80%) rename apps/{claude-code-plugin => agent-plugin}/scripts/preload-model.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/scripts/reset.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/scripts/status.sh (96%) rename apps/{claude-code-plugin => agent-plugin}/scripts/stop.sh (100%) rename apps/{claude-code-plugin => agent-plugin}/skills/init/SKILL.md (94%) rename apps/{claude-code-plugin => agent-plugin}/skills/recall/SKILL.md (100%) rename apps/{claude-code-plugin => agent-plugin}/skills/remember/SKILL.md (100%) rename apps/{claude-code-plugin => agent-plugin}/skills/reset/SKILL.md (100%) rename apps/{claude-code-plugin => agent-plugin}/skills/status/SKILL.md (100%) rename apps/{claude-code-plugin => agent-plugin}/skills/stop/SKILL.md (100%) rename apps/{claude-code-plugin => agent-plugin}/watcher/README.md (100%) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 522babc20..1629d8e2f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "plugins": [ { "name": "memory-powermem", - "source": "./apps/claude-code-plugin", + "source": "./apps/agent-plugin", "description": "PowerMem intelligent memory for Claude Code and Codex CLI: Claude Code uses HTTP hooks; Codex CLI uses skills with explicit MCP wiring.", "category": "memory", "tags": ["memory", "powermem", "rag", "hooks", "mcp", "codex", "oceanbase"] diff --git a/.github/workflows/plugins-build.yml b/.github/workflows/plugins-build.yml index 455900adf..6a6638390 100644 --- a/.github/workflows/plugins-build.yml +++ b/.github/workflows/plugins-build.yml @@ -64,8 +64,8 @@ jobs: path: apps/vscode-extension/*.vsix retention-days: 30 - package-claude-plugin: - name: Package Claude Code Plugin + package-agent-plugin: + name: Package Agent Plugin runs-on: ubuntu-latest steps: @@ -77,20 +77,20 @@ jobs: with: go-version: ${{ env.GO_VERSION }} - - name: Package Claude Code plugin (cross-compile hooks + zip) - run: bash apps/claude-code-plugin/scripts/package-plugin.sh + - name: Package agent plugin (cross-compile hooks + zip) + run: bash apps/agent-plugin/scripts/package-plugin.sh - - name: Upload Claude Code plugin (zip) + - name: Upload agent plugin (zip) uses: actions/upload-artifact@v7 with: - name: powermem-claude-code-plugin-zip - path: apps/claude-code-plugin/dist/powermem-claude-code-plugin-*.zip + name: powermem-agent-plugin-zip + path: apps/agent-plugin/dist/powermem-agent-plugin-*.zip if-no-files-found: error retention-days: 30 release-plugins: name: Release Plugin Assets runs-on: ubuntu-latest - needs: [build-vscode-extension, package-claude-plugin] + needs: [build-vscode-extension, package-agent-plugin] if: startsWith(github.ref, 'refs/tags/plugins-') || (github.event_name == 'workflow_dispatch' && github.event.inputs.create_release == 'true') permissions: contents: write @@ -102,10 +102,10 @@ jobs: name: powermem-vscode-vsix path: vsix - - name: Download Claude Code plugin + - name: Download agent plugin uses: actions/download-artifact@v8 with: - name: powermem-claude-code-plugin-zip + name: powermem-agent-plugin-zip path: zip - name: Get version from tag or default @@ -126,12 +126,12 @@ jobs: ## PowerMem IDE Plugins - **PowerMem for VS Code** (`.vsix`): Download and install from VSIX in VS Code or Cursor. - - **PowerMem for Claude Code** (`.zip`): Download, unzip, and start Claude with `claude --plugin-dir /path/to/powermem-claude-code-plugin`. + - **PowerMem agent plugin** (`.zip`): Download, unzip, and start Claude with `claude --plugin-dir /path/to/powermem-agent-plugin`; Codex CLI installs through `codex plugin`. See [apps/README.md](https://github.com/${{ github.repository }}/blob/main/apps/README.md). files: | vsix/*.vsix - zip/powermem-claude-code-plugin-*.zip + zip/powermem-agent-plugin-*.zip draft: false prerelease: ${{ contains(github.ref, 'refs/tags/') == false }} generate_release_notes: true diff --git a/Makefile b/Makefile index 01d4639dd..c0cc2a20b 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help install install-dev test test-unit test-integration test-e2e test-coverage test-fast test-slow check-python-version lint lint-full lint-pylint format clean build build-package build-check build-mcp-package build-mcp-check build-all-python-packages build-dashboard build-claude-hook package-claude-plugin publish-pypi publish-mcp-pypi publish-all-pypi publish-testpypi install-build-tools upload docs bump-version check-package-versions server-start server-stop server-restart server-status server-logs server-dashboard-start docker-build docker-run docker-up docker-down docker-logs docker-stop docker-restart docker-clean docker-ps +.PHONY: help install install-dev test test-unit test-integration test-e2e test-coverage test-fast test-slow check-python-version lint lint-full lint-pylint format clean build build-package build-check build-mcp-package build-mcp-check build-all-python-packages build-dashboard build-claude-hook package-agent-plugin package-claude-plugin publish-pypi publish-mcp-pypi publish-all-pypi publish-testpypi install-build-tools upload docs bump-version check-package-versions server-start server-stop server-restart server-status server-logs server-dashboard-start docker-build docker-run docker-up docker-down docker-logs docker-stop docker-restart docker-clean docker-ps PYTHON ?= python3 @@ -152,11 +152,13 @@ build-dashboard: ## Build dashboard frontend and inject into src/server/dashboar @cp -r dashboard/dist/* src/server/dashboard/ @echo "✓ Dashboard built. Start server with: make server-start-reload (then open http://localhost:$(SERVER_PORT)/dashboard/)" -build-claude-hook: ## Build Claude Code hook binaries (Go; output: apps/claude-code-plugin/hooks/bin/) - @bash apps/claude-code-plugin/scripts/build-hook-binaries.sh +build-claude-hook: ## Build Claude Code hook binaries (Go; output: apps/agent-plugin/hooks/bin/) + @bash apps/agent-plugin/scripts/build-hook-binaries.sh -package-claude-plugin: ## Zip Claude Code plugin for sharing (apps/claude-code-plugin/dist/*.zip) - @bash apps/claude-code-plugin/scripts/package-plugin.sh +package-agent-plugin: ## Zip Agent plugin for sharing (apps/agent-plugin/dist/*.zip) + @bash apps/agent-plugin/scripts/package-plugin.sh + +package-claude-plugin: package-agent-plugin ## Compatibility alias for package-agent-plugin install-build-tools: ## Install build and upload tools @echo "Installing build tools..." diff --git a/README.md b/README.md index 77d985437..9570b7cb9 100644 --- a/README.md +++ b/README.md @@ -120,10 +120,10 @@ cd powermem Then open Claude Code in your terminal and paste this one line: ```text -Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code. +Read and follow apps/agent-plugin/SETUP.md to set up PowerMem memory for Claude Code. ``` -Claude Code reads [`apps/claude-code-plugin/SETUP.md`](apps/claude-code-plugin/SETUP.md), asks you for the few required secrets, and wires everything up end-to-end. +Claude Code reads [`apps/agent-plugin/SETUP.md`](apps/agent-plugin/SETUP.md), asks you for the few required secrets, and wires everything up end-to-end. #### Manual setup diff --git a/README_CN.md b/README_CN.md index a1e4e0467..8a68114df 100644 --- a/README_CN.md +++ b/README_CN.md @@ -110,10 +110,10 @@ cd powermem 在终端打开 Claude Code，粘贴下面这一行： ```text -Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code. +Read and follow apps/agent-plugin/SETUP.md to set up PowerMem memory for Claude Code. ``` -Claude Code 会阅读 [`apps/claude-code-plugin/SETUP.md`](apps/claude-code-plugin/SETUP.md)，向你询问少量必要密钥，并端到端完成全部配置。 +Claude Code 会阅读 [`apps/agent-plugin/SETUP.md`](apps/agent-plugin/SETUP.md)，向你询问少量必要密钥，并端到端完成全部配置。 #### 手动配置 diff --git a/README_JP.md b/README_JP.md index 03ba584cb..5b2bcf22d 100644 --- a/README_JP.md +++ b/README_JP.md @@ -110,10 +110,10 @@ cd powermem ターミナルで Claude Code を開き、次の一行を貼り付けます: ```text -Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code. +Read and follow apps/agent-plugin/SETUP.md to set up PowerMem memory for Claude Code. ``` -Claude Code は [`apps/claude-code-plugin/SETUP.md`](apps/claude-code-plugin/SETUP.md) を読み、必要な秘密情報だけを尋ね、エンドツーエンドで設定を完了します。 +Claude Code は [`apps/agent-plugin/SETUP.md`](apps/agent-plugin/SETUP.md) を読み、必要な秘密情報だけを尋ね、エンドツーエンドで設定を完了します。 #### 手動セットアップ diff --git a/apps/README.md b/apps/README.md index dfde7caaf..35b5c9cfb 100644 --- a/apps/README.md +++ b/apps/README.md @@ -8,10 +8,10 @@ First-party setup flows that connect PowerMem to AI clients and IDEs. Every path |-------------|-------------------|------------------------| | **Cursor**, **VS Code**, **Windsurf**, **GitHub Copilot**, **Qoder** | [`vscode-extension/`](vscode-extension/) | `Read and follow apps/vscode-extension/SETUP.md to setup PowerMem` | | **Claude Desktop**, **Cline**, **OpenCode**, Roo Code, Goose, or any other MCP client | [`mcp-client/`](mcp-client/) | `Read and follow apps/mcp-client/SETUP.md to setup PowerMem` | -| **Codex CLI** | [`claude-code-plugin/`](claude-code-plugin/) | Install `memory-powermem` with `codex plugin`, then ask Codex to use the init skill. | -| **Claude Code** (hook-based plugin) | [`claude-code-plugin/`](claude-code-plugin/) | `Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code.` | +| **Codex CLI** | [`agent-plugin/`](agent-plugin/) | Install `memory-powermem` with `codex plugin`, then ask Codex to use the init skill. | +| **Claude Code** (hook-based plugin) | [`agent-plugin/`](agent-plugin/) | `Read and follow apps/agent-plugin/SETUP.md to set up PowerMem memory for Claude Code.` | -> **Codex CLI** has a native plugin path under `claude-code-plugin/`; generic +> **Codex CLI** has a native plugin path under `agent-plugin/`; generic > MCP-only Codex setup can still use `mcp-client/`. **OpenCode** belongs under > `mcp-client/`, not `vscode-extension/`. The VS Code extension flow is for > VS Code–compatible IDEs only. @@ -24,7 +24,7 @@ For **OpenClaw**, use the separate [`memory-powermem`](https://github.com/ob-lab |-----------|-------------| | **[vscode-extension](vscode-extension/)** | VS Code extension and agent-guided setup for Cursor, VS Code, Windsurf, GitHub Copilot, and Qoder. Commands: Query memories, Add selection, Quick note, Link to AI tools, Setup, Dashboard. | | **[mcp-client](mcp-client/)** | Agent-guided setup for generic MCP clients (Claude Desktop, Cline, OpenCode, and others). Uses `powermem-mcp` directly; prefers SSE on port `8848`. | -| **[claude-code-plugin](claude-code-plugin/)** | Claude Code and Codex CLI plugin descriptors. Claude Code uses **HTTP mode by default** (REST hooks; empty `mcpServers`). Codex CLI uses skills plus explicit `codex mcp add`. Optional Claude **MCP mode** via [`config/mcp-mode.mcp.json`](claude-code-plugin/config/mcp-mode.mcp.json). | +| **[agent-plugin](agent-plugin/)** | Claude Code and Codex CLI plugin descriptors. Claude Code uses **HTTP mode by default** (REST hooks; empty `mcpServers`). Codex CLI uses skills plus explicit `codex mcp add`. Optional Claude **MCP mode** via [`config/mcp-mode.mcp.json`](agent-plugin/config/mcp-mode.mcp.json). | ## Quick start @@ -56,7 +56,7 @@ All setup flows share the same backend priority: 3. **Fall back** to MCP-only only when HTTP is unavailable: `powermem-mcp sse 8848` (or streamable HTTP / stdio when the target client requires it) -The `mcp-client/` path uses `powermem-mcp` directly and prefers SSE on port `8848`. The `vscode-extension/` path prefers the HTTP API and links the current IDE/client first. The `claude-code-plugin/` path defaults to HTTP hooks for Claude Code, and provides a Codex CLI plugin that manages init/status/stop/reset skills while MCP is added explicitly with `codex mcp add`. +The `mcp-client/` path uses `powermem-mcp` directly and prefers SSE on port `8848`. The `vscode-extension/` path prefers the HTTP API and links the current IDE/client first. The `agent-plugin/` path defaults to HTTP hooks for Claude Code, and provides a Codex CLI plugin that manages init/status/stop/reset skills while MCP is added explicitly with `codex mcp add`. ## Setup & uninstall guides @@ -64,7 +64,7 @@ The `mcp-client/` path uses `powermem-mcp` directly and prefers SSE on port `884 |-----------|-------|-----------|---------| | `vscode-extension/` | [SETUP.md](vscode-extension/SETUP.md) | [UNINSTALL.md](vscode-extension/UNINSTALL.md) | [README.md](vscode-extension/README.md) | | `mcp-client/` | [SETUP.md](mcp-client/SETUP.md) | [UNINSTALL.md](mcp-client/UNINSTALL.md) | — | -| `claude-code-plugin/` | [SETUP.md](claude-code-plugin/SETUP.md) | [UNINSTALL.md](claude-code-plugin/UNINSTALL.md) | [README.md](claude-code-plugin/README.md) | +| `agent-plugin/` | [SETUP.md](agent-plugin/SETUP.md) | [UNINSTALL.md](agent-plugin/UNINSTALL.md) | [README.md](agent-plugin/README.md) | ## Per-client manual guides diff --git a/apps/claude-code-plugin/.claude-plugin/marketplace.json b/apps/agent-plugin/.claude-plugin/marketplace.json similarity index 100% rename from apps/claude-code-plugin/.claude-plugin/marketplace.json rename to apps/agent-plugin/.claude-plugin/marketplace.json diff --git a/apps/claude-code-plugin/.claude-plugin/plugin.json b/apps/agent-plugin/.claude-plugin/plugin.json similarity index 100% rename from apps/claude-code-plugin/.claude-plugin/plugin.json rename to apps/agent-plugin/.claude-plugin/plugin.json diff --git a/apps/claude-code-plugin/.codex-plugin/plugin.json b/apps/agent-plugin/.codex-plugin/plugin.json similarity index 98% rename from apps/claude-code-plugin/.codex-plugin/plugin.json rename to apps/agent-plugin/.codex-plugin/plugin.json index 589f67bf1..76f9a5224 100644 --- a/apps/claude-code-plugin/.codex-plugin/plugin.json +++ b/apps/agent-plugin/.codex-plugin/plugin.json @@ -7,7 +7,7 @@ "email": "open_oceanbase@oceanbase.com", "url": "https://github.com/oceanbase" }, - "homepage": "https://github.com/oceanbase/powermem/tree/main/apps/claude-code-plugin", + "homepage": "https://github.com/oceanbase/powermem/tree/main/apps/agent-plugin", "repository": "https://github.com/oceanbase/powermem", "license": "Apache-2.0", "keywords": ["memory", "powermem", "codex", "mcp", "oceanbase"], diff --git a/apps/claude-code-plugin/.gitignore b/apps/agent-plugin/.gitignore similarity index 100% rename from apps/claude-code-plugin/.gitignore rename to apps/agent-plugin/.gitignore diff --git a/apps/claude-code-plugin/.mcp.json b/apps/agent-plugin/.mcp.json similarity index 100% rename from apps/claude-code-plugin/.mcp.json rename to apps/agent-plugin/.mcp.json diff --git a/apps/claude-code-plugin/CHANGELOG.md b/apps/agent-plugin/CHANGELOG.md similarity index 91% rename from apps/claude-code-plugin/CHANGELOG.md rename to apps/agent-plugin/CHANGELOG.md index 70c29ee8f..b9dfc4f78 100644 --- a/apps/claude-code-plugin/CHANGELOG.md +++ b/apps/agent-plugin/CHANGELOG.md @@ -27,4 +27,4 @@ Initial release of the PowerMem plugin for Claude Code. - Optional workspace file poller: `sh hooks/run-hook.sh poll` (see `watcher/README.md`). - Windows: `hooks/hooks.windows.example.json` + PowerShell `run-hook.ps1` when `sh` is unavailable. -- Packaging: `scripts/package-plugin.sh` / `make package-claude-plugin`; hook binaries via `scripts/build-hook-binaries.sh` (Go 1.22+). +- Packaging: `scripts/package-plugin.sh` / `make package-agent-plugin`; hook binaries via `scripts/build-hook-binaries.sh` (Go 1.22+). diff --git a/apps/claude-code-plugin/README.md b/apps/agent-plugin/README.md similarity index 98% rename from apps/claude-code-plugin/README.md rename to apps/agent-plugin/README.md index 9dabfb8dd..a0fc222e5 100644 --- a/apps/claude-code-plugin/README.md +++ b/apps/agent-plugin/README.md @@ -15,7 +15,7 @@ This directory contains the plugin descriptors and shared runtime files To load it directly in Claude Code: ```bash -claude --plugin-dir /path/to/powermem/apps/claude-code-plugin +claude --plugin-dir /path/to/powermem/apps/agent-plugin ``` ## Claude Code Marketplace Install diff --git a/apps/claude-code-plugin/SETUP.md b/apps/agent-plugin/SETUP.md similarity index 98% rename from apps/claude-code-plugin/SETUP.md rename to apps/agent-plugin/SETUP.md index c680ba39d..08cafc8a1 100644 --- a/apps/claude-code-plugin/SETUP.md +++ b/apps/agent-plugin/SETUP.md @@ -2,7 +2,7 @@ This file is a **prompt for Claude Code**. Open Claude Code in your terminal and say: -> Read and follow `apps/claude-code-plugin/SETUP.md` to set up PowerMem memory for Claude Code. +> Read and follow `apps/agent-plugin/SETUP.md` to set up PowerMem memory for Claude Code. Claude Code will then run the steps below: detect whether you are in the PowerMem source tree or not, ask you for the few required secrets, and wire PowerMem up as a @@ -195,7 +195,7 @@ state and either skip, reuse, or refresh it instead of failing or duplicating wo 1. DETECT CONTEXT. The current directory is the PowerMem source tree if a pyproject.toml here has name = "powermem" (or src/powermem/ and - apps/claude-code-plugin/ both exist). Tell me which path you will take: + apps/agent-plugin/ both exist). Tell me which path you will take: - SOURCE -> build & deploy from this checkout and install the Claude Code plugin GLOBALLY in HTTP mode (hooks -> REST; needs Go 1.22+). - PIP -> install from PyPI and connect via the powermem-mcp server @@ -430,8 +430,8 @@ writing. Never silently patch `.env`.** ~/.claude/marketplaces/powermem: DEST="$HOME/.claude/marketplaces/powermem" mkdir -p "$DEST" - rsync -a --delete "/apps/claude-code-plugin/" "$DEST/" - # no rsync? rm -rf "$DEST" && cp -a "/apps/claude-code-plugin/." "$DEST/" + rsync -a --delete "/apps/agent-plugin/" "$DEST/" + # no rsync? rm -rf "$DEST" && cp -a "/apps/agent-plugin/." "$DEST/" The binaries from `make build-claude-hook` must already be on disk before this copy. Re-copy on every re-run so the staged dir tracks your latest build. - Register the marketplace from the STAGED dir (it ships @@ -613,7 +613,7 @@ writing. Never silently patch `.env`.** This file is safe to re-run end to end. The only manual-feeling case is refreshing the cached plugin after you change the plugin or rebuild the Go hooks at the SAME version: rebuild (`make build-claude-hook`), re-copy the result into the staged -marketplace (`rsync -a --delete /apps/claude-code-plugin/ ~/.claude/marketplaces/powermem/`), +marketplace (`rsync -a --delete /apps/agent-plugin/ ~/.claude/marketplaces/powermem/`), then force-refresh the cache with `claude plugin uninstall memory-powermem@powermem` followed by `claude plugin install memory-powermem@powermem --scope user` (or bump the version in .claude-plugin/plugin.json so `claude plugin update memory-powermem` picks it up). @@ -872,7 +872,7 @@ make build-claude-hook # Register marketplace DEST="$HOME/.claude/marketplaces/powermem" mkdir -p "$DEST" -rsync -a --delete "$(pwd)/apps/claude-code-plugin/" "$DEST/" +rsync -a --delete "$(pwd)/apps/agent-plugin/" "$DEST/" claude plugin marketplace add "$DEST" claude plugin install memory-powermem@powermem --scope user diff --git a/apps/claude-code-plugin/UNINSTALL.md b/apps/agent-plugin/UNINSTALL.md similarity index 94% rename from apps/claude-code-plugin/UNINSTALL.md rename to apps/agent-plugin/UNINSTALL.md index d6790c632..8d7d32024 100644 --- a/apps/claude-code-plugin/UNINSTALL.md +++ b/apps/agent-plugin/UNINSTALL.md @@ -2,7 +2,7 @@ This file is a **prompt for Claude Code**. Open Claude Code in your terminal and say: -> Read and follow `apps/claude-code-plugin/UNINSTALL.md` to remove PowerMem from Claude Code. +> Read and follow `apps/agent-plugin/UNINSTALL.md` to remove PowerMem from Claude Code. It reverses everything `SETUP.md` did: it unregisters the plugin/MCP server, removes the staged marketplace copy (~/.claude/marketplaces/powermem), stops the PowerMem API server, @@ -25,7 +25,7 @@ confirmation — those steps are gated below. 1. DETECT CONTEXT. The current directory is the PowerMem source tree if a pyproject.toml here has name = "powermem" (or src/powermem/ and - apps/claude-code-plugin/ both exist). Tell me which path applies: + apps/agent-plugin/ both exist). Tell me which path applies: - SOURCE -> global plugin install (HTTP hooks) was used. - PIP -> the powermem-mcp server (MCP) was used. If unsure, check both: `claude plugin list` (look for memory-powermem@powermem) @@ -72,9 +72,9 @@ confirmation — those steps are gated below. the integration, and some destroy data: - Build artifacts (SOURCE): delete the compiled hook binaries (rm -rf never errors when the dir is already gone): - rm -rf apps/claude-code-plugin/hooks/bin + rm -rf apps/agent-plugin/hooks/bin (You may also restore the committed default if it drifted: - git checkout -- apps/claude-code-plugin/.mcp.json 2>/dev/null || true) + git checkout -- apps/agent-plugin/.mcp.json 2>/dev/null || true) - Stored memories (DESTRUCTIVE — this erases all my saved memories): the embedded seekdb data lives in `./seekdb_data/` (or the path in my .env). For SQLite storage mode, data lives in `./sqlite_data/`. diff --git a/apps/claude-code-plugin/cmd/powermem-hook/detach_unix.go b/apps/agent-plugin/cmd/powermem-hook/detach_unix.go similarity index 100% rename from apps/claude-code-plugin/cmd/powermem-hook/detach_unix.go rename to apps/agent-plugin/cmd/powermem-hook/detach_unix.go diff --git a/apps/claude-code-plugin/cmd/powermem-hook/detach_windows.go b/apps/agent-plugin/cmd/powermem-hook/detach_windows.go similarity index 100% rename from apps/claude-code-plugin/cmd/powermem-hook/detach_windows.go rename to apps/agent-plugin/cmd/powermem-hook/detach_windows.go diff --git a/apps/claude-code-plugin/cmd/powermem-hook/main.go b/apps/agent-plugin/cmd/powermem-hook/main.go similarity index 100% rename from apps/claude-code-plugin/cmd/powermem-hook/main.go rename to apps/agent-plugin/cmd/powermem-hook/main.go diff --git a/apps/claude-code-plugin/cmd/powermem-hook/poll.go b/apps/agent-plugin/cmd/powermem-hook/poll.go similarity index 100% rename from apps/claude-code-plugin/cmd/powermem-hook/poll.go rename to apps/agent-plugin/cmd/powermem-hook/poll.go diff --git a/apps/claude-code-plugin/config/README.md b/apps/agent-plugin/config/README.md similarity index 100% rename from apps/claude-code-plugin/config/README.md rename to apps/agent-plugin/config/README.md diff --git a/apps/claude-code-plugin/config/http-mode.mcp.json b/apps/agent-plugin/config/http-mode.mcp.json similarity index 100% rename from apps/claude-code-plugin/config/http-mode.mcp.json rename to apps/agent-plugin/config/http-mode.mcp.json diff --git a/apps/claude-code-plugin/config/mcp-mode.mcp.json b/apps/agent-plugin/config/mcp-mode.mcp.json similarity index 100% rename from apps/claude-code-plugin/config/mcp-mode.mcp.json rename to apps/agent-plugin/config/mcp-mode.mcp.json diff --git a/apps/claude-code-plugin/go.mod b/apps/agent-plugin/go.mod similarity index 100% rename from apps/claude-code-plugin/go.mod rename to apps/agent-plugin/go.mod diff --git a/apps/claude-code-plugin/hooks/bin/powermem-hook-darwin-amd64 b/apps/agent-plugin/hooks/bin/powermem-hook-darwin-amd64 similarity index 100% rename from apps/claude-code-plugin/hooks/bin/powermem-hook-darwin-amd64 rename to apps/agent-plugin/hooks/bin/powermem-hook-darwin-amd64 diff --git a/apps/claude-code-plugin/hooks/bin/powermem-hook-darwin-arm64 b/apps/agent-plugin/hooks/bin/powermem-hook-darwin-arm64 similarity index 100% rename from apps/claude-code-plugin/hooks/bin/powermem-hook-darwin-arm64 rename to apps/agent-plugin/hooks/bin/powermem-hook-darwin-arm64 diff --git a/apps/claude-code-plugin/hooks/bin/powermem-hook-linux-amd64 b/apps/agent-plugin/hooks/bin/powermem-hook-linux-amd64 similarity index 100% rename from apps/claude-code-plugin/hooks/bin/powermem-hook-linux-amd64 rename to apps/agent-plugin/hooks/bin/powermem-hook-linux-amd64 diff --git a/apps/claude-code-plugin/hooks/bin/powermem-hook-linux-arm64 b/apps/agent-plugin/hooks/bin/powermem-hook-linux-arm64 similarity index 100% rename from apps/claude-code-plugin/hooks/bin/powermem-hook-linux-arm64 rename to apps/agent-plugin/hooks/bin/powermem-hook-linux-arm64 diff --git a/apps/claude-code-plugin/hooks/bin/powermem-hook-windows-amd64.exe b/apps/agent-plugin/hooks/bin/powermem-hook-windows-amd64.exe similarity index 100% rename from apps/claude-code-plugin/hooks/bin/powermem-hook-windows-amd64.exe rename to apps/agent-plugin/hooks/bin/powermem-hook-windows-amd64.exe diff --git a/apps/claude-code-plugin/hooks/hooks.json b/apps/agent-plugin/hooks/hooks.json similarity index 100% rename from apps/claude-code-plugin/hooks/hooks.json rename to apps/agent-plugin/hooks/hooks.json diff --git a/apps/claude-code-plugin/hooks/hooks.windows.example.json b/apps/agent-plugin/hooks/hooks.windows.example.json similarity index 100% rename from apps/claude-code-plugin/hooks/hooks.windows.example.json rename to apps/agent-plugin/hooks/hooks.windows.example.json diff --git a/apps/claude-code-plugin/hooks/run-hook.ps1 b/apps/agent-plugin/hooks/run-hook.ps1 similarity index 100% rename from apps/claude-code-plugin/hooks/run-hook.ps1 rename to apps/agent-plugin/hooks/run-hook.ps1 diff --git a/apps/claude-code-plugin/hooks/run-hook.sh b/apps/agent-plugin/hooks/run-hook.sh similarity index 100% rename from apps/claude-code-plugin/hooks/run-hook.sh rename to apps/agent-plugin/hooks/run-hook.sh diff --git a/apps/claude-code-plugin/init-flow.png b/apps/agent-plugin/init-flow.png similarity index 100% rename from apps/claude-code-plugin/init-flow.png rename to apps/agent-plugin/init-flow.png diff --git a/apps/claude-code-plugin/init-flow.svg b/apps/agent-plugin/init-flow.svg similarity index 100% rename from apps/claude-code-plugin/init-flow.svg rename to apps/agent-plugin/init-flow.svg diff --git a/apps/claude-code-plugin/scripts/apply-connection-mode.sh b/apps/agent-plugin/scripts/apply-connection-mode.sh similarity index 100% rename from apps/claude-code-plugin/scripts/apply-connection-mode.sh rename to apps/agent-plugin/scripts/apply-connection-mode.sh diff --git a/apps/claude-code-plugin/scripts/build-hook-binaries.sh b/apps/agent-plugin/scripts/build-hook-binaries.sh similarity index 100% rename from apps/claude-code-plugin/scripts/build-hook-binaries.sh rename to apps/agent-plugin/scripts/build-hook-binaries.sh diff --git a/apps/claude-code-plugin/scripts/common.sh b/apps/agent-plugin/scripts/common.sh similarity index 100% rename from apps/claude-code-plugin/scripts/common.sh rename to apps/agent-plugin/scripts/common.sh diff --git a/apps/claude-code-plugin/scripts/init.sh b/apps/agent-plugin/scripts/init.sh similarity index 99% rename from apps/claude-code-plugin/scripts/init.sh rename to apps/agent-plugin/scripts/init.sh index 4e1c7e3c2..3ed48304a 100755 --- a/apps/claude-code-plugin/scripts/init.sh +++ b/apps/agent-plugin/scripts/init.sh @@ -5,7 +5,7 @@ SCRIPT_DIR=$(CDPATH= cd -- "$(dirname "$0")" && pwd) # shellcheck disable=SC1091 . "$SCRIPT_DIR/common.sh" -echo "PowerMem Claude Code plugin init" +echo "PowerMem agent plugin init" echo "Data dir: $DATA_DIR" base_url=$(runtime_base_url) @@ -281,7 +281,7 @@ server_log_file = env_first("POWERMEM_SERVER_LOG_FILE") or path_value("powermem- logging_level = env_first("LOGGING_LEVEL") or "INFO" lines = [ - "# Generated by the PowerMem Claude Code plugin.", + "# Generated by the PowerMem agent plugin.", "", "# Core paths", f"POWERMEM_DATA_DIR={data_dir}", diff --git a/apps/claude-code-plugin/scripts/package-plugin.sh b/apps/agent-plugin/scripts/package-plugin.sh similarity index 80% rename from apps/claude-code-plugin/scripts/package-plugin.sh rename to apps/agent-plugin/scripts/package-plugin.sh index 9e988c85d..9fcff382c 100755 --- a/apps/claude-code-plugin/scripts/package-plugin.sh +++ b/apps/agent-plugin/scripts/package-plugin.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# Build a portable zip of the Claude Code plugin for sharing or offline install. -# Output: apps/claude-code-plugin/dist/powermem-claude-code-plugin-.zip +# Build a portable zip of the PowerMem agent plugin for sharing or offline install. +# Output: apps/agent-plugin/dist/powermem-agent-plugin-.zip set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -8,7 +8,7 @@ PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" DIST="${PLUGIN_ROOT}/dist" VERSION="$(python3 -c "import json; print(json.load(open('${PLUGIN_ROOT}/.claude-plugin/plugin.json'))['version'])")" -ZIP_NAME="powermem-claude-code-plugin-${VERSION}.zip" +ZIP_NAME="powermem-agent-plugin-${VERSION}.zip" ZIP_PATH="${DIST}/${ZIP_NAME}" if ! command -v zip >/dev/null 2>&1; then @@ -23,7 +23,7 @@ TMP="$(mktemp -d)" cleanup() { rm -rf "${TMP}"; } trap cleanup EXIT -STAGE="${TMP}/powermem-claude-code-plugin" +STAGE="${TMP}/powermem-agent-plugin" mkdir -p "${STAGE}" cp -R "${PLUGIN_ROOT}/.claude-plugin" "${STAGE}/" @@ -40,7 +40,7 @@ cp -R "${PLUGIN_ROOT}/skills" "${STAGE}/" [[ -d "${PLUGIN_ROOT}/cmd" ]] && cp -R "${PLUGIN_ROOT}/cmd" "${STAGE}/" [[ -d "${PLUGIN_ROOT}/scripts" ]] && cp -R "${PLUGIN_ROOT}/scripts" "${STAGE}/" -( cd "${TMP}" && zip -r "${ZIP_PATH}" "powermem-claude-code-plugin" -x "*.DS_Store" -x "*__pycache__*" -x "*.pyc" ) +( cd "${TMP}" && zip -r "${ZIP_PATH}" "powermem-agent-plugin" -x "*.DS_Store" -x "*__pycache__*" -x "*.pyc" ) echo "Packaged: ${ZIP_PATH}" ls -lh "${ZIP_PATH}" diff --git a/apps/claude-code-plugin/scripts/preload-model.sh b/apps/agent-plugin/scripts/preload-model.sh similarity index 100% rename from apps/claude-code-plugin/scripts/preload-model.sh rename to apps/agent-plugin/scripts/preload-model.sh diff --git a/apps/claude-code-plugin/scripts/reset.sh b/apps/agent-plugin/scripts/reset.sh similarity index 100% rename from apps/claude-code-plugin/scripts/reset.sh rename to apps/agent-plugin/scripts/reset.sh diff --git a/apps/claude-code-plugin/scripts/status.sh b/apps/agent-plugin/scripts/status.sh similarity index 96% rename from apps/claude-code-plugin/scripts/status.sh rename to apps/agent-plugin/scripts/status.sh index fced43f1e..7b64601aa 100755 --- a/apps/claude-code-plugin/scripts/status.sh +++ b/apps/agent-plugin/scripts/status.sh @@ -7,7 +7,7 @@ SCRIPT_DIR=$(CDPATH= cd -- "$(dirname "$0")" && pwd) base_url=$(runtime_base_url) -echo "PowerMem Claude Code plugin status" +echo "PowerMem agent plugin status" echo "Data dir: $DATA_DIR" echo "Runtime file: $RUNTIME_FILE" echo "Env file: $ENV_FILE" diff --git a/apps/claude-code-plugin/scripts/stop.sh b/apps/agent-plugin/scripts/stop.sh similarity index 100% rename from apps/claude-code-plugin/scripts/stop.sh rename to apps/agent-plugin/scripts/stop.sh diff --git a/apps/claude-code-plugin/skills/init/SKILL.md b/apps/agent-plugin/skills/init/SKILL.md similarity index 94% rename from apps/claude-code-plugin/skills/init/SKILL.md rename to apps/agent-plugin/skills/init/SKILL.md index cdc243aa9..7ee66eaf8 100644 --- a/apps/claude-code-plugin/skills/init/SKILL.md +++ b/apps/agent-plugin/skills/init/SKILL.md @@ -5,7 +5,7 @@ description: Initialize PowerMem for Claude Code or Codex CLI after the plugin i Initialize PowerMem for Claude Code or Codex CLI. -Read `apps/claude-code-plugin/SETUP.md`, section "Installed plugin initialization", +Read `apps/agent-plugin/SETUP.md`, section "Installed plugin initialization", and follow only that section. Do not run the source/developer setup flow from `SETUP.md`: do not build hook diff --git a/apps/claude-code-plugin/skills/recall/SKILL.md b/apps/agent-plugin/skills/recall/SKILL.md similarity index 100% rename from apps/claude-code-plugin/skills/recall/SKILL.md rename to apps/agent-plugin/skills/recall/SKILL.md diff --git a/apps/claude-code-plugin/skills/remember/SKILL.md b/apps/agent-plugin/skills/remember/SKILL.md similarity index 100% rename from apps/claude-code-plugin/skills/remember/SKILL.md rename to apps/agent-plugin/skills/remember/SKILL.md diff --git a/apps/claude-code-plugin/skills/reset/SKILL.md b/apps/agent-plugin/skills/reset/SKILL.md similarity index 100% rename from apps/claude-code-plugin/skills/reset/SKILL.md rename to apps/agent-plugin/skills/reset/SKILL.md diff --git a/apps/claude-code-plugin/skills/status/SKILL.md b/apps/agent-plugin/skills/status/SKILL.md similarity index 100% rename from apps/claude-code-plugin/skills/status/SKILL.md rename to apps/agent-plugin/skills/status/SKILL.md diff --git a/apps/claude-code-plugin/skills/stop/SKILL.md b/apps/agent-plugin/skills/stop/SKILL.md similarity index 100% rename from apps/claude-code-plugin/skills/stop/SKILL.md rename to apps/agent-plugin/skills/stop/SKILL.md diff --git a/apps/claude-code-plugin/watcher/README.md b/apps/agent-plugin/watcher/README.md similarity index 100% rename from apps/claude-code-plugin/watcher/README.md rename to apps/agent-plugin/watcher/README.md diff --git a/docs/integrations/claude_code.md b/docs/integrations/claude_code.md index 1b04ecc66..bc55b2d1a 100644 --- a/docs/integrations/claude_code.md +++ b/docs/integrations/claude_code.md @@ -1,18 +1,18 @@ # Claude Code -Give [Claude Code](https://code.claude.com) persistent, self-evolving memory through the first-party plugin (`memory-powermem`, under [`apps/claude-code-plugin/`](https://github.com/oceanbase/powermem/tree/main/apps/claude-code-plugin/)). +Give [Claude Code](https://code.claude.com) persistent, self-evolving memory through the first-party plugin (`memory-powermem`, under [`apps/agent-plugin/`](https://github.com/oceanbase/powermem/tree/main/apps/agent-plugin/)). -This page is the single source of truth for the Claude Code integration — the plugin's own [`README.md`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/README.md) links here. +This page is the single source of truth for the Claude Code integration — the plugin's own [`README.md`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/README.md) links here. ## Fastest path — let Claude Code set itself up Open Claude Code in your terminal and paste this one line: ```text -Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code. +Read and follow apps/agent-plugin/SETUP.md to set up PowerMem memory for Claude Code. ``` -Claude Code reads [`apps/claude-code-plugin/SETUP.md`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/SETUP.md) — the canonical automated-setup prompt — which detects whether you are in the PowerMem **source tree** (developer) or anywhere else (**pip user**), asks you for the few required secrets, and wires everything up end-to-end. +Claude Code reads [`apps/agent-plugin/SETUP.md`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/SETUP.md) — the canonical automated-setup prompt — which detects whether you are in the PowerMem **source tree** (developer) or anywhere else (**pip user**), asks you for the few required secrets, and wires everything up end-to-end. Prefer to wire it by hand? The full plugin reference below covers every option. @@ -22,9 +22,9 @@ Prefer to wire it by hand? The full plugin reference below covers every option. - **Two connection modes** (aligned with the PowerMem VS Code extension). **HTTP mode is the default** (standard): REST-only via hooks, no PowerMem MCP tools in chat. **MCP mode** is optional when you want `search_memories` / `add_memory` in the conversation. See [Configuration](#configuration). - **HTTP mode (default)**: Root `.mcp.json` ships with empty `mcpServers`. Hooks use **`POST /api/v1/memories`** (`POWERMEM_BASE_URL`, default `http://localhost:8848`). -- **MCP mode (optional)**: Copy [`config/mcp-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/config/mcp-mode.mcp.json) to `.mcp.json` (or run `apply-connection-mode.sh mcp`). Claude gets PowerMem tools over **HTTP** `…/mcp` or **stdio**. +- **MCP mode (optional)**: Copy [`config/mcp-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/config/mcp-mode.mcp.json) to `.mcp.json` (or run `apply-connection-mode.sh mcp`). Claude gets PowerMem tools over **HTTP** `…/mcp` or **stdio**. - **Skills**: `/memory-powermem:remember` and `/memory-powermem:recall` — effective in **MCP mode**; in default HTTP mode they cannot drive tools. -- **Seamless REST capture**: Hooks run in **both** modes. Optional **file poller** — see [watcher/README.md](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/watcher/README.md). +- **Seamless REST capture**: Hooks run in **both** modes. Optional **file poller** — see [watcher/README.md](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/watcher/README.md). - **Auto-retrieval (no MCP required, on by default)**: The `UserPromptSubmit` hook calls **`POST /api/v1/memories/search`** with the user’s prompt and injects hits via [`additionalContext`](https://code.claude.com/docs/en/hooks#userpromptsubmit). Set **`POWERMEM_PROMPT_SEARCH=0`** (or `false` / `no` / `off`) to disable — saves a search round-trip per turn. Works in **HTTP and MCP** modes. ## Runtime requirements (end users) @@ -34,18 +34,18 @@ Prefer to wire it by hand? The full plugin reference below covers every option. | Claude Code | No | | | MCP tools | No | **Off by default** (HTTP mode). Run `apply-connection-mode.sh mcp` to enable. | | **Hooks** (transcript / compact → HTTP API) | **No** | Native binaries under `hooks/bin/` + `run-hook.sh` (macOS/Linux) or PowerShell on Windows. **`POWERMEM_BASE_URL` defaults to `http://localhost:8848`.** | -| Optional **file poller** | No | Same binary: `sh hooks/run-hook.sh poll` — see [watcher/README.md](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/watcher/README.md). | +| Optional **file poller** | No | Same binary: `sh hooks/run-hook.sh poll` — see [watcher/README.md](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/watcher/README.md). | **macOS / Linux:** default `hooks/hooks.json` runs `sh …/run-hook.sh`. POSIX `sh` is always present. -**Windows (native, no Git Bash):** if `sh` is missing, merge the commands from [`hooks/hooks.windows.example.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/hooks/hooks.windows.example.json) into your Claude `settings.json` so hooks call `powershell.exe -File …/run-hook.ps1`. The zip includes `hooks/bin/powermem-hook-windows-amd64.exe` (add `windows/arm64` to the build script if you need it). +**Windows (native, no Git Bash):** if `sh` is missing, merge the commands from [`hooks/hooks.windows.example.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/hooks/hooks.windows.example.json) into your Claude `settings.json` so hooks call `powershell.exe -File …/run-hook.ps1`. The zip includes `hooks/bin/powermem-hook-windows-amd64.exe` (add `windows/arm64` to the build script if you need it). -**Rebuilding binaries** (developers / CI): Go **1.22+**, then `bash scripts/build-hook-binaries.sh` or `make build-claude-hook` from the repo root. `make package-claude-plugin` builds them automatically before zipping. +**Rebuilding binaries** (developers / CI): Go **1.22+**, then `bash scripts/build-hook-binaries.sh` or `make build-claude-hook` from the repo root. `make package-agent-plugin` builds them automatically before zipping. ## Prerequisites 1. **PowerMem HTTP API** reachable from the machine running Claude (e.g. `powermem-server --port 8848`). Default hooks use **`http://localhost:8848`** — override with `POWERMEM_BASE_URL` for a remote server. -2. **MCP mode only:** additionally expose MCP (same host, usually `/mcp`) or stdio `powermem-mcp`, and switch `.mcp.json` via [`config/mcp-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/config/mcp-mode.mcp.json). +2. **MCP mode only:** additionally expose MCP (same host, usually `/mcp`) or stdio `powermem-mcp`, and switch `.mcp.json` via [`config/mcp-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/config/mcp-mode.mcp.json). 3. **Claude Code** (VS Code extension or CLI) with plugin support. ## Manual Installation @@ -89,7 +89,7 @@ Every available setting is documented under [Configuration](#configuration); `pm ```bash pip install -e '.[server,seekdb]' -make build-claude-hook # outputs apps/claude-code-plugin/hooks/bin/ +make build-claude-hook # outputs apps/agent-plugin/hooks/bin/ ``` ### Step 4 — Start the HTTP API server @@ -103,7 +103,7 @@ powermem-server --host 0.0.0.0 --port 8848 ### Step 5 — Load the plugin into Claude Code ```bash -claude --plugin-dir "$(pwd)/apps/claude-code-plugin" +claude --plugin-dir "$(pwd)/apps/agent-plugin" ``` ### Step 6 — Verify @@ -117,7 +117,7 @@ End the session (or run `/compact`), then look for `POST /api/v1/memories` in th #### Option A: Load from directory (development) ```bash -claude --plugin-dir /path/to/powermem/apps/claude-code-plugin +claude --plugin-dir /path/to/powermem/apps/agent-plugin ``` #### Option B: Install from marketplace @@ -155,31 +155,31 @@ POWERMEM_INIT_PACKAGE='powermem @ git+https://github.com/oceanbase/powermem.git@ From the **powermem repo root**: ```bash -make package-claude-plugin +make package-agent-plugin ``` Or run the script directly: ```bash -bash apps/claude-code-plugin/scripts/package-plugin.sh +bash apps/agent-plugin/scripts/package-plugin.sh ``` -This writes **`apps/claude-code-plugin/dist/powermem-claude-code-plugin-.zip`**. Share that zip (USB, internal artifact server, etc.). +This writes **`apps/agent-plugin/dist/powermem-agent-plugin-.zip`**. Share that zip (USB, internal artifact server, etc.). **On the other computer:** -1. Unzip → you get a folder `powermem-claude-code-plugin/` containing `.claude-plugin/`, `hooks/`, `skills/`, `.mcp.json`, etc. +1. Unzip → you get a folder `powermem-agent-plugin/` containing `.claude-plugin/`, `hooks/`, `skills/`, `.mcp.json`, etc. 2. Point Claude Code at that folder (absolute path recommended): ```bash # Optional: hooks default to http://localhost:8848 if POWERMEM_BASE_URL is unset export POWERMEM_BASE_URL=https://your-team-powermem.example.com # team server only - claude --plugin-dir /path/to/powermem-claude-code-plugin + claude --plugin-dir /path/to/powermem-agent-plugin ``` 3. Requirements on that machine: **no Python**; use **macOS/Linux** `sh` or follow **Windows** PowerShell hooks above. **HTTP API** must be reachable for hooks (and `/mcp` too if you enable MCP mode). -To publish a zip **with MCP enabled by default**, replace root `.mcp.json` with `config/mcp-mode.mcp.json` before `make package-claude-plugin`, or document that users run `apply-connection-mode.sh mcp`. +To publish a zip **with MCP enabled by default**, replace root `.mcp.json` with `config/mcp-mode.mcp.json` before `make package-agent-plugin`, or document that users run `apply-connection-mode.sh mcp`. ## Uninstall and update @@ -193,7 +193,7 @@ How you remove the plugin depends on how you enabled it: | **Zip / copied folder** | Delete the unzipped directory. Stop using `--plugin-dir` pointing at it. | | **Git clone / repo path** | Stop using `--plugin-dir` for that path; remove the clone if you no longer need it. | | **Marketplace / built-in plugin UI** | Run `/plugin uninstall memory-powermem@powermem`, then `/reload-plugins`. To remove the marketplace entry as well, run `/plugin marketplace remove powermem`. | -| **You merged [`hooks/hooks.windows.example.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/hooks/hooks.windows.example.json) into `settings.json`** | Edit `~/.claude/settings.json` or `.claude/settings.json` in the project and remove the `UserPromptSubmit` / `SessionEnd` / `PostCompact` hook entries that call `run-hook.ps1` (or restore a backup). Otherwise hooks keep running even after the plugin folder is deleted. | +| **You merged [`hooks/hooks.windows.example.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/hooks/hooks.windows.example.json) into `settings.json`** | Edit `~/.claude/settings.json` or `.claude/settings.json` in the project and remove the `UserPromptSubmit` / `SessionEnd` / `PostCompact` hook entries that call `run-hook.ps1` (or restore a backup). Otherwise hooks keep running even after the plugin folder is deleted. | The hook binary only **writes** to your PowerMem server; it does not install a system daemon. No separate “service uninstall” is required. @@ -201,8 +201,8 @@ The hook binary only **writes** to your PowerMem server; it does not install a s | Install style | Update steps | |---------------|--------------| -| **Zip** | Download the new `.zip`, replace the old folder (delete the previous `powermem-claude-code-plugin` tree, unzip the new one to the same or a new path), then start Claude with `--plugin-dir` pointing at the new folder. | -| **Repo / `git`** | `git pull` (or fetch the release you want), run `make package-claude-plugin` or `bash scripts/package-plugin.sh` if you need a fresh zip, then restart Claude Code. | +| **Zip** | Download the new `.zip`, replace the old folder (delete the previous `powermem-agent-plugin` tree, unzip the new one to the same or a new path), then start Claude with `--plugin-dir` pointing at the new folder. | +| **Repo / `git`** | `git pull` (or fetch the release you want), run `make package-agent-plugin` or `bash scripts/package-plugin.sh` if you need a fresh zip, then restart Claude Code. | | **Marketplace** | Run `/plugin uninstall memory-powermem@powermem`, reinstall from the marketplace, then run `/reload-plugins`. If the backend package changed, re-run `/memory-powermem:init` so the plugin-local venv installs the new PyPI release. | After updating, restart the Claude Code session (or the whole app) so MCP config, skills, and hooks reload. @@ -215,8 +215,8 @@ Same **MCP / HTTP** split as elsewhere in PowerMem. **Standard shipping = HTTP m | Mode | Plugin root `.mcp.json` | Claude in-chat | Silent capture (hooks → REST) | |------|-------------------------|----------------|--------------------------------| -| **HTTP mode (default)** | Empty `mcpServers` — same as [`config/http-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/config/http-mode.mcp.json) | No PowerMem MCP tools | Yes (`POWERMEM_BASE_URL`, default `http://localhost:8848`) | -| **MCP mode** | Includes `powermem` — [`config/mcp-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/config/mcp-mode.mcp.json) | Yes — `search_memories`, `add_memory`, … | Yes | +| **HTTP mode (default)** | Empty `mcpServers` — same as [`config/http-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/config/http-mode.mcp.json) | No PowerMem MCP tools | Yes (`POWERMEM_BASE_URL`, default `http://localhost:8848`) | +| **MCP mode** | Includes `powermem` — [`config/mcp-mode.mcp.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/config/mcp-mode.mcp.json) | Yes — `search_memories`, `add_memory`, … | Yes | **Switch mode** (from the plugin directory): @@ -225,7 +225,7 @@ bash scripts/apply-connection-mode.sh http # restore standard (default) HTTP-on bash scripts/apply-connection-mode.sh mcp # enable in-chat PowerMem tools ``` -Restart Claude Code after changing `.mcp.json`. See [`config/README.md`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/config/README.md). +Restart Claude Code after changing `.mcp.json`. See [`config/README.md`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/config/README.md). **Naming note:** In **MCP mode**, `transport: "http"` means “connect to the **MCP** endpoint over HTTP” (`https://host/mcp`), not “replace MCP with REST.” **HTTP mode** means “no MCP entry for PowerMem”; REST is still used by hooks. @@ -266,7 +266,7 @@ This is the **default** root `.mcp.json`. Claude has **no** PowerMem MCP tools; ### Seamless recording (hooks + HTTP API) -The plugin ships [`hooks/hooks.json`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/hooks/hooks.json), [`hooks/run-hook.sh`](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/hooks/run-hook.sh), and **native** `hooks/bin/powermem-hook-*` (built from [`cmd/powermem-hook`](https://github.com/oceanbase/powermem/tree/main/apps/claude-code-plugin/cmd/powermem-hook/)). When the plugin is enabled, Claude Code merges these hooks: +The plugin ships [`hooks/hooks.json`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/hooks/hooks.json), [`hooks/run-hook.sh`](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/hooks/run-hook.sh), and **native** `hooks/bin/powermem-hook-*` (built from [`cmd/powermem-hook`](https://github.com/oceanbase/powermem/tree/main/apps/agent-plugin/cmd/powermem-hook/)). When the plugin is enabled, Claude Code merges these hooks: | Hook | What happens | |------|----------------| @@ -324,7 +324,7 @@ export POWERMEM_WATCH_ROOT=/path/to/repo sh hooks/run-hook.sh poll ``` -See [watcher/README.md](https://github.com/oceanbase/powermem/blob/main/apps/claude-code-plugin/watcher/README.md) for environment variables. +See [watcher/README.md](https://github.com/oceanbase/powermem/blob/main/apps/agent-plugin/watcher/README.md) for environment variables. ## Usage