Use the paxm MCP tools for active recall and explicit memory writes. Treat recalled memory as supporting context and verify changing facts in the current repository. Passive hooks are owned by this plugin after the user runs paxm setup --integration claude-plugin.

Set up paxm for Codex

Run this workflow only when the user asks to configure, repair, or verify paxm. Do not silently install a binary, write provider credentials, or modify Codex hooks.

1. Diagnose first

Run the read-only checks:

paxm version
paxm config doctor --json

If paxm is not on PATH, check the standard user install locations before offering installation. Explain that the installer downloads the latest release binary by default and ask for explicit approval before running:

curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash

When a reproducible install or rollback is required, export a compatible release before running the command:

export PAXM_VERSION=v0.1.20
curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash

After installation, run paxm version again and report the resolved path. The equivalent bundled helper is scripts/install-paxm.sh when the plugin's absolute install path is available; do not assume PLUGIN_ROOT exists in a skill shell environment.

2. Configure the plugin-owned integration

Ask the user to choose providers and passive behavior, then run the interactive setup with Codex plugin ownership:

paxm setup --integration codex-plugin

The equivalent bundled helper is scripts/setup-paxm.sh when its absolute plugin path is available. This keeps provider credentials and profiles in paxm while preventing paxm from registering a duplicate global Codex hook. The plugin's own hook definitions remain subject to Codex's normal /hooks review and trust flow.

3. Verify the loop

After setup:

1. Run paxm config doctor.
2. Write one random test fact to STM and immediately recall it.
3. Explain which provider answered and that the test fact will expire.
4. Ask the user to start a fresh Codex task or submit one prompt so the passive hook can be observed.
5. Use paxm history --days 1 to confirm the hook event.

If a check fails, identify the layer (plugin, binary, config, provider, hook trust, or Codex task lifecycle) and give one next action. Do not reinstall everything by default.

Safety rules

• Never print or echo provider API keys.
• Never modify ~/.codex/config.toml from a setup script.
• Never bypass Codex hook trust.
• Hook failures must not block the user's Codex task.
• Keep MCP optional until the binary and plugin-owned hook path are healthy.

paxm memory

Use paxm as a supporting memory layer, not as a replacement for current source verification. Keep setup, credentials, provider selection, and passive hook policy under the user's control.

Before using memory

Check the local installation only when the task needs memory:

paxm version
paxm config doctor

If the binary is missing, ask the user before running the bundled installer. If the config is missing or invalid, ask whether to start the interactive setup flow. Do not edit paxm YAML by hand.

Active recall

Use a short, concrete query and a small result limit:

paxm recall --query "repo decision about hook ownership" --limit 3 --json

For a custom config, pass --config before the subcommand. Read scores and provider metadata, then verify facts that may have changed in the current repo. If a result exposes a precise lead, do at most two or three focused follow-up queries rather than running an open-ended search loop.

When the host exposes paxm MCP tools, prefer paxm_recall, paxm_remember, paxm_history, and paxm_config_doctor over shelling out.

Remember

Use STM for task-local working state:

paxm remember --profile stm --text "Working note: ..."

Use LTM only for durable decisions, preferences, recurring fixes, or stable project conventions:

paxm remember --profile ltm --text "Decision: ..."

Never store secrets, API keys, access tokens, raw private logs, or large pasted transcripts. Ask before storing sensitive personal or business information.

Passive recall and diagnostics

Passive Codex hooks are installed by this plugin only after the user completes the plugin-aware setup flow. Do not run a second paxm setup without the --integration codex-plugin mode, because that would change hook ownership.

When debugging, use bounded local history and logs:

paxm history --days 7 --json
paxm logs --tail 50

Treat memory as supporting evidence. Current repository files, current tool output, and explicit user instructions take precedence over recalled content.

paxm

Use paxm to actively recall and record memory while keeping setup and provider policy under the user's control. Active agent writes should use short-term memory (stm) unless the user or evidence clearly calls for durable long-term memory (ltm).

Prerequisites

Prefer the installed paxm on PATH.

Check availability when needed:

paxm version
paxm config doctor

If paxm is missing, tell the user to install it from this repository:

curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash

If paxm config doctor says config is missing or invalid, the user needs one interactive setup pass:

paxm setup

paxm setup lets the user choose memory provider instances and passive agent integrations for Codex, Claude Code, or Pi. It does not install active recall skills; the user owns that installation. Active recall needs at least one enabled readable provider instance. sqlite works without an API key; remote providers such as Zep or Mem0 require the user to provide their own connection details during setup, and JSON-RPC plugin providers require a local plugin command. Passive hook recall only works after hooks are installed by setup, but active commands still work independently. Passive hook writes use long-term memory (ltm) by default; active agent writes should normally use stm.

If the user gives a config path, pass it through every command:

paxm --config /path/to/config.yaml recall --query "..." --json

MCP Mode

When the host has paxm configured as an MCP server, prefer the structured MCP tools over shelling out:

• paxm_recall instead of paxm recall --json
• paxm_remember instead of paxm remember; pass profile: "stm" for working memory or profile: "ltm" for durable facts
• paxm_history instead of paxm history --json
• paxm_config_doctor instead of paxm config doctor --json

The server command is:

paxm mcp serve

For a custom config:

paxm --config /path/to/config.yaml mcp serve

MCP mode follows the same operating rules as CLI mode. Do not use it to run setup, install hooks, uninstall integrations, or backfill old sessions.

Active Recall

Before answering a question that depends on prior project decisions, user preferences, repo history, or old debugging context, run a targeted recall:

paxm recall --query "short concrete query" --limit 3 --json

Use a query that captures the user's current task, not the whole prompt. Include stable identifiers when available: repo name, module name, command, error text, feature name, issue id, or decision keyword.

Read scores and provider metadata. Treat memory as supporting context, not source of truth. Verify against the current repo or live system when the fact can drift, is high stakes, or is cheap to check.

If recall returns nothing relevant, continue normally and do not imply memory found evidence.

Multi-Hop Recall

Use multi-hop recall when the first results expose a more precise lead than the original query: a repo/module name, document title, issue id, symbol, command, error text, provider metadata, or decision keyword.

Workflow:

1. Run an initial focused recall with a small limit.
2. Read the highest-scoring hits and extract one or two concrete follow-up terms that were not in the original query.
3. Run another recall for each useful follow-up term, keeping the query short and specific.
4. Merge the evidence across hops, then verify against the current repo or live system when the fact can drift or direct verification is cheap.

Example:

paxm recall --query "Roundtable translation language preference" --limit 3 --json
paxm recall --query "content_translations translation_jobs DeepSeek provider" --limit 3 --json

Do not run open-ended recall loops. Stop after 2-3 hops, when a hop returns no new concrete lead, or when the next step should be repo or web verification instead of more memory search. Do not treat a follow-up hit as confirmed truth without checking current source when accuracy matters.

Remember

Use short-term memory for active task state that may help the next few turns or near-future follow-ups:

paxm remember --profile stm --text "Working note: PR #42 is blocked on the mem0 tier-filter test."

Use long-term memory only for durable, reusable facts:

paxm remember --profile ltm --text "Decision: paxm setup owns provider and hook configuration; visible hook install/test commands are intentionally omitted."

Paxm consolidates exact repeated LTM text when no explicit ID is supplied. This does not make semantic duplicates or conflicting statements safe: keep durable memories concise and consistently worded, and verify current source before relying on facts that may drift.

Good ltm candidates:

• user preferences that should affect future agent behavior;
• project architecture decisions and settled terminology;
• commands or fixes that resolved a recurring issue;
• repo-specific conventions that are likely to matter again.

Do not store secrets, API keys, access tokens, private raw logs, or large pasted content. Do not promote short-lived task state to ltm; keep it in stm. Ask before storing sensitive personal or business information.

Debugging Memory Use

Use history to inspect local recall/write activity and provider behavior:

paxm history --days 7
paxm history --days 7 --json

Use logs when aggregate history is not enough and the user wants recent event details or live debugging:

paxm logs --tail 100
paxm logs --tail 100 --json
paxm logs --tail 0 --follow

Prefer a bounded tail. Use --follow only for an explicit live-monitoring task, and stop it when that task is complete. Raw logs are local CLI data; there is no MCP logs tool.

Use this when the user asks whether passive recall fired, why a memory was not recalled, which providers were read or written, or how often agents are using memory.

Operating Rules

• Keep active recall conservative: do not inject weakly related memories into the answer.
• Use stm for active scratchpad-like writes and ltm only for durable facts.
• Prefer --json for agent consumption because it includes structured scores and provider fields.
• Keep --limit small by default; use --limit 5 or higher only when the task genuinely needs broader context.
• Do not run paxm setup silently. It is interactive and changes user-owned config and hooks.
• Do not run paxm uninstall silently. It removes passive agent integrations; use --agent to scope cleanup and --yes only with explicit user approval.
• Do not edit paxm config files by hand unless the user explicitly asks; prefer paxm setup for configuration.
• Do not treat passive hook behavior as guaranteed unless setup installed hooks and history shows events.
• Do not look for or run a manual memory cleanup command. Expired STM cleanup is a best-effort hook-flush side effect managed by the hook daemon, and recall filters expired rows even before storage cleanup runs.

Check paxm version and paxm config doctor. With user approval, run ${CLAUDE_PLUGIN_ROOT}/scripts/setup-paxm.sh. Provider credentials and hook policy remain user-controlled. Verify ownership and a real remember/recall smoke test afterward.