What changes after installation

In one session, record a decision:

paxm remember --profile ltm --text \
  "Production deploys run through GitHub Actions; never deploy from a laptop"

In a later session, Codex, Claude Code, OpenCode, Pi, or an MCP client can recover it:

paxm recall --query "how do we deploy production?"

With passive integration enabled, paxm recalls relevant context before the agent responds and durably captures completed turns afterward. Provider delays or failures do not block the coding session.

The practical result:

• New sessions resume with project context instead of making you restate architecture decisions, conventions, and operational constraints.
• One memory path works across agents. A decision captured from Codex can be recalled from Claude Code, OpenCode, Pi, or any MCP client.
• Your storage stays your choice. Start with local SQLite, connect Zep, Mem0, MemOS, or OpenViking, or bring a private provider through JSON-RPC.
• You retain control. Credentials, hook trust, routing, data location, disable, uninstall, and rollback remain user-owned.

Quick start

Choose the agent you already use. The Codex plugin is the shortest path to a complete active-and-passive memory loop.

Codex plugin

codex plugin marketplace add pax-beehive/paxm --ref paxm-memory-v0.1.4
codex plugin add paxm-memory@pax-agent-nexus
curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash
paxm setup --integration codex-plugin

Start a new Codex task and trust the Pax Agent neXus hooks when /hooks asks. The explicit installer downloads the latest published paxm binary. The plugin registers active-memory skills and owns the passive Codex hooks after setup; it never installs a binary, writes credentials, or bypasses hook trust on its own.

Verify the first successful loop before relying on passive memory:

paxm config doctor
paxm remember --profile stm --text "PAXM_FIRST_RECALL_OK"
paxm recall --query "PAXM_FIRST_RECALL_OK"
paxm history --days 1

Set PAXM_VERSION before installation for a reproducible version or rollback. Provider credentials remain user-managed. Team Memory can derive a scoped agent credential from a paxl device connection; paxm never writes that secret to config.yaml.

Claude Code plugin

Install the paxm CLI, then install the Claude Code plugin:

curl -fsSL https://github.com/pax-beehive/paxm/releases/latest/download/install.sh | bash
claude plugin marketplace add pax-beehive/paxm
claude plugin install paxm-claude@pax-memory
paxm setup --integration claude-plugin

The Claude plugin includes active-memory skills, the paxm MCP server, and five lifecycle hooks: SessionStart, UserPromptSubmit, PostToolUse, PostToolUseFailure, and Stop.

Session bootstrap injects the configured user, agent, and session identity together with the current local time and time zone. Codex, Claude Code, and Pi use their session-start events; OpenCode performs the same bootstrap before the first message in a session. If a later user input arrives more than 12 hours after the preceding turn activity, paxm refreshes the local-time context before the agent handles that input.

OpenCode, Pi, CLI, or MCP

Install the latest release and run interactive setup. The default SQLite provider makes the adaptor usable without first creating an account or API key.

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

paxm setup asks only two questions: which providers to enable and which agents get passive memory. Agents found on the machine are pre-selected and marked (detected), and cloud provider API keys are masked as they are typed. Everything else uses the tuned defaults. When Team Memory is selected, setup first reads the on-prem user ID from paxl device status, with channel status as a compatibility fallback; otherwise the user ID comes from $USER. Agents get IDs such as codex-todd, and selected providers route read/write as required. Use up/down to move, space to toggle, and enter to confirm. Fine-tuning (paths, profiles, routing policy, per-hook behavior) lives in the config file; see docs/config.md.

Optional team IDs create explicit durable write profiles such as team-pax-core; non-interactive setup can pass --user-id todd --team-id pax-core. Scripts can also skip the selection prompts entirely with repeatable flags, e.g. paxm setup --provider sqlite --agent codex --agent claude.

Active recall skills remain user-installed. SQLite works without an API key; remote providers such as Zep, Mem0, MemOS, and OpenViking require connection details during setup.

SQLite health checks must be allowed to create WAL/SHM files beside the configured database. A sandbox that can read the database but cannot write its parent directory may report SQLite error 14.

Use an isolated writable SQLite path for sandboxed evaluations. The same configuration may be healthy in the real agent process.

When Codex is using the bundled paxm-memory plugin, let the plugin own Codex's hooks so paxm does not register a duplicate global hook:

Write and recall a memory:

paxm remember --profile ltm --text "We chose SQLite for the local memory layer"
paxm recall --query "local memory layer"
paxm history --days 7
paxm dashboard   # localhost metrics, logs, sessions, and recall inspection

Select OpenCode during setup to install a global local plugin under ~/.config/opencode/plugins/. Select Pi to install its passive extension. Cursor, TRAE, TRAE CN, Kimi Code, ZCode, Kiro, and Cline selections install a client-native hook/MCP integration while preserving unrelated client config. See the agent integration matrix for exact event mappings, paths, host limitations, verification, and rollback. Any MCP-compatible client can use paxm mcp serve --agent codex; replace codex with the configured client identity.

SQLite quality preview

SQLite gives a new user a complete local memory loop before they choose or deploy a dedicated memory system. It uses FTS5 and BM25 retrieval with turn-level memories and deterministic, query-focused excerpts. Memory ingestion and retrieval call no external LLM or embedding service.

In an initial 30-question LoCoMo agent evaluation, SQLite turn memory answered 13 questions successfully, compared with 11 for Mem0 product-default.

This is an exploratory result, not an official LoCoMo score or proof that SQLite broadly outperforms Mem0. It covers one balanced conversation with OpenCode and DeepSeek V4 Flash, using deterministic token F1. See the methodology and limitations.

How it works

PAXM is a memory adaptor, not another hosted memory service:

AI agents  ->  CLI / MCP / skills / hooks  ->  paxm  ->  any memory provider

Agents reach paxm in two ways:

Both paths use the same runtime and provider router. Filtering, profiles, ranking, timeouts, telemetry, and provider behavior stay consistent across agent surfaces.

Passive writes commit to a local durable queue before provider delivery. Slow or unavailable providers retry in the background instead of blocking the agent.

Passive recall uses an 800ms overall budget and 250ms per-provider budget by default. It returns healthy partial results and records downstream timeouts.

See it in motion

Read the detailed architecture and provider adapter contract.

Stored memories distinguish their origin (user, agent, session, and turn) from their visibility scope. Providers that advertise attribution support must round-trip both values; see the JSON-RPC provider protocol.

Agents and providers

Agent surfaces

Memory providers

Enable multiple provider instances at once. Recall and write profiles control routes, required or best-effort behavior, ranking weights, thresholds, memory tiers, and timeouts.

Team Memory through a paxl device

Connect the workstation once, then select Team Memory during setup:

paxl device connect onprem \
  --url https://memory.company.internal \
  --device-name todd-macbook-air \
  --enrollment-token tm_enroll_xxx
paxm setup

If TEAM_MEMORY_API_KEY is explicitly configured, paxm preserves the existing behavior and does not call paxl. Otherwise the Team Memory adapter runs paxl device provision --agent <PAXM_AGENT_ID> --json, caches the returned agent credential under ~/.config/paxm/credentials/ with mode 0600, and passes the URL, user ID, agent ID, and key only to paxm-team-memory-provider. A provider 401 triggers one re-provision and one retry; a second failure is returned to the caller. If paxl or its device credential is unavailable, the error directs the operator to run paxl device connect onprem.

Passive capture uses the trusted hook origin to route each Team Memory batch through that agent's credential. On a shared workstation, Codex and Claude captures therefore use separate team-<agent-id>.json caches and are attributed to their own Team Memory principals. A rejected credential is re-provisioned only for the affected agent. Paxm passes the trusted hook target as paxl's explicit agent type, so legacy IDs such as claude-<user> do not depend on suffix inference. Captures without a resolved origin fall back to the configured PAXM_AGENT_ID; an explicit TEAM_MEMORY_API_KEY keeps the legacy single-credential behavior.

Mem0 score direction is deployment-specific. score_semantics defaults to similarity for backward compatibility; set it to distance when the Mem0 endpoint returns pgvector cosine distance. Paxm cannot infer this from a field named score or similarity.

Self-hosted Mem0 search scope placement is also version-dependent. search_scope_payload: auto sends user_id, agent_id, and run_id inside filters first, then retries once with top-level fields only when the server returns a recognized missing-scope compatibility error. Set top_level for Mem0 0.1.117-style servers or filters for strict nested-filter deployments.

Self-hosted OpenViking

OpenViking support connects paxm to a user-operated OpenViking server. Writes are recorded through OpenViking sessions and committed for asynchronous memory extraction. Recall uses semantic memory search through /api/v1/search/find. The server URL and optional API key remain in the user's paxm configuration.

Run paxm setup, select OpenViking, and provide the self-hosted base URL and API key. OpenViking can then participate in the same recall and write profiles as SQLite or any other provider, with required or best-effort routing and provider-specific timeouts.

MCP server

Run paxm as a local stdio MCP server:

paxm mcp serve --agent codex

{
  "command": "paxm",
  "args": ["mcp", "serve", "--agent", "codex"]
}

The server exposes four focused tools:

• paxm_recall
• paxm_remember
• paxm_history
• paxm_config_doctor

Setup, credential management, hook installation, and backfill stay outside MCP so an agent cannot silently take ownership of user configuration.

Writes carry user, agent, and named personal/team scope provenance. Recall does not filter by that scope: CLI, MCP, and passive injection label every result with its source scope, while provider-native routing and ACL remain under the provider's control. Active CLI calls derive a stable session identity from the configured user, config path, and current workspace. An MCP server creates one session identity at startup and reuses it for that server lifetime. Paxm passes these values as runtime recall context and structured write provenance, never as provider search filters.

Agent integrations

Codex plugin

The Codex plugin packages the paxm setup skill, active memory skill, and native Codex hooks. It does not install provider credentials or bypass hook trust.

Use paxm setup --integration codex-plugin so only the plugin owns the Codex lifecycle hooks.

Claude Code plugin

The Claude Code plugin is a first-class integration, not a generic setup shim. It packages skills, an MCP server, and five native lifecycle hooks.

Setup removes only legacy paxm-managed Claude hooks, preserves unrelated hooks, and records claude-plugin ownership.

Pi extension

Pi support is installed through paxm setup. The extension handles passive prompt recall and buffers visible user, assistant, and tool events into one turn-end memory while excluding thinking blocks.

OpenCode plugin

OpenCode support is installed through paxm setup as a dependency-free global plugin. The plugin uses OpenCode's chat.message and model-message transform hooks for passive recall.

On session.idle, it reads the completed session through the official client and writes a durable turn. It captures visible user and assistant text while excluding reasoning and tool payloads.

The generated plugin lives at ~/.config/opencode/plugins/paxm.ts, or below OPENCODE_CONFIG_DIR/XDG_CONFIG_HOME when configured.

See the complete configuration guide for generated paths, event mappings, profile settings, and uninstall behavior.

Reliability by default

• Hook acknowledgement waits only for the local queue transaction.
• Provider delivery is resumable and retried in the background.
• Optional provider failures do not discard healthy provider results.
• A stuck provider is contained by its timeout and single-call bulkhead.
• Write-provider routes default to a 30-second timeout; optional failures remain isolated while required-provider failures are returned to the caller.
• Recall provenance is stripped before passive writes to prevent memory echo.
• Session-scoped writes receive a persisted monotonic sequence, preventing same-timestamp events from colliding across paxm processes.
• Exact LTM consolidation limits duplicate accumulation.
• SQLite preserves completed agent turns with explicit session, turn, and time boundaries.
• Telemetry stores hashes and lengths by default, not raw recall queries.

Historical imports are also resumable:

paxm backfill scan --agent codex --after 2026-07-21
paxm backfill run --agent codex --provider mem0-company --after 2026-07-21 --background
paxm backfill status --agent codex --provider mem0-company

--after is inclusive and --before is exclusive. Supplying --after without --before intentionally scans through the latest session history, including turns after passive capture was enabled.

Performance

Benchmarks use runtime-generated temporary datasets modeled after real passive agent workloads; no benchmark corpus is committed to the repository.

On an Apple M4 reference machine:

These numbers measure the adapter, not end-to-end agent response time. See the datasets, commands, allocations, and machine details in SQLite adapter benchmarks.

Evaluation

paxm separates deterministic regression suites from paid, real-agent quality evaluations. CI protects runtime behavior; opt-in benchmarks measure whether memory helps an agent answer correctly.

The repository includes deterministic production-path evaluations:

go run ./cmd/paxm eval run --suite evals/baseline
go run ./cmd/paxm eval run --suite evals/conversation-write

• A 100-case retrieval suite reports recall@K, precision@K, MRR, false-positive rate, latency, and category-level results.
• A 50-case conversation-to-write suite checks admission, recall, forbidden fragments, metadata preservation, and adapter contract behavior.

CI runs unit tests, vet, the retrieval report, and the adapter write contract on every push to main and every pull request.

The opt-in LoCoMo agent benchmark exercises real OpenCode sessions and production MCP or passive recall.

The cross-agent benchmark tests whether one agent's experience helps another avoid the same failure.

Paid agent evaluations are never run in ordinary CI. Their reports separate memory-layer cost from answering-model cost and state their evidence limits.

Documentation

Community

• Ask setup questions, share successful workflows, and discuss early ideas in GitHub Discussions.
• Report reproducible bugs or request a demand-backed integration through the repository's structured issue forms.
• Read CONTRIBUTING.md before proposing a substantial change.
• Report suspected vulnerabilities privately according to SECURITY.md.

Development

go test ./...
go vet ./...
go build -o /tmp/paxm ./cmd/paxm
/tmp/paxm --config /tmp/paxm-dev/config.yaml setup --force

Releases

Releases cover macOS, Linux, and Windows on amd64 and arm64. Published archives include SHA256SUMS, and the installer verifies the selected archive before replacing the binary.

See the release guide for validation, tagging, asset, and installer smoke-test requirements.