[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93322":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":14,"stars30d":14,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":13,"starSnapshotCount":13,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},93322,"paxm","pax-beehive\u002Fpaxm","pax-beehive","Persistent, provider-neutral memory for Codex, Claude Code, OpenCode, Pi, and MCP coding agents.",null,"Go",111,1,0,4,43.3,"Apache License 2.0",false,"main",true,[21,22,23,24,25,26,27,28,29],"agent-memory","ai-agents","claude-code","codex","golang","local-first","mcp","opencode","sqlite","2026-07-22 04:02:08","\u003Cdiv align=\"center\">\n\n# PAXM\n\n### Stop re-explaining your project to every new coding-agent session.\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Factions\u002Fworkflows\u002Fci.yml)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fpax-beehive\u002Fpaxm)](https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Freleases\u002Flatest)\n[![Go](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fgo-mod\u002Fgo-version\u002Fpax-beehive\u002Fpaxm)](go.mod)\n[![Platforms](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS%20%7C%20Linux%20%7C%20Windows-6f42c1)](https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Freleases\u002Flatest)\n\nPAXM carries decisions, conventions, and working context into later Codex,\nClaude Code, OpenCode, Pi, and MCP sessions. Start locally with SQLite and no\naccount, API key, embeddings, or extra memory-layer model calls. Change memory\nproviders later without rewiring every agent.\n\n[Install for Codex](#codex-plugin) · [Install the CLI](#opencode-pi-cli-or-mcp) · [See the result](#what-changes-after-installation) · [Docs](#documentation) · [中文](docs\u002FREADME.zh-CN.md)\n\n\u003C\u002Fdiv>\n\n## What changes after installation\n\nIn one session, record a decision:\n\n```bash\npaxm remember --profile ltm --text \\\n  \"Production deploys run through GitHub Actions; never deploy from a laptop\"\n```\n\nIn a later session, Codex, Claude Code, OpenCode, Pi, or an MCP client can\nrecover it:\n\n```bash\npaxm recall --query \"how do we deploy production?\"\n```\n\nWith passive integration enabled, paxm recalls relevant context before the\nagent responds and durably captures completed turns afterward. Provider delays\nor failures do not block the coding session.\n\nThe practical result:\n\n- **New sessions resume with project context** instead of making you restate\n  architecture decisions, conventions, and operational constraints.\n- **One memory path works across agents.** A decision captured from Codex can\n  be recalled from Claude Code, OpenCode, Pi, or any MCP client.\n- **Your storage stays your choice.** Start with local SQLite, connect Zep,\n  Mem0, MemOS, or OpenViking, or bring a private provider through JSON-RPC.\n- **You retain control.** Credentials, hook trust, routing, data location,\n  disable, uninstall, and rollback remain user-owned.\n\n## Quick start\n\nChoose the agent you already use. The Codex plugin is the shortest path to a\ncomplete active-and-passive memory loop.\n\n### Codex plugin\n\n```bash\ncodex plugin marketplace add pax-beehive\u002Fpaxm --ref paxm-memory-v0.1.4\ncodex plugin add paxm-memory@pax-agent-nexus\ncurl -fsSL https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Freleases\u002Flatest\u002Fdownload\u002Finstall.sh | bash\npaxm setup --integration codex-plugin\n```\n\nStart a new Codex task and trust the Pax Agent neXus hooks when `\u002Fhooks` asks.\nThe explicit installer downloads the latest published paxm binary. The plugin\nregisters active-memory skills and owns the passive Codex hooks after setup;\nit never installs a binary, writes credentials, or bypasses hook trust on its\nown.\n\nVerify the first successful loop before relying on passive memory:\n\n```bash\npaxm config doctor\npaxm remember --profile stm --text \"PAXM_FIRST_RECALL_OK\"\npaxm recall --query \"PAXM_FIRST_RECALL_OK\"\npaxm history --days 1\n```\n\nSet `PAXM_VERSION` before installation for a reproducible version or rollback.\nProvider credentials remain user-managed.\n\n### Claude Code plugin\n\nInstall the paxm CLI, then install the Claude Code plugin:\n\n```bash\ncurl -fsSL https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Freleases\u002Flatest\u002Fdownload\u002Finstall.sh | bash\nclaude plugin marketplace add pax-beehive\u002Fpaxm\nclaude plugin install paxm-claude@pax-memory\npaxm setup --integration claude-plugin\n```\n\nThe Claude plugin includes active-memory skills, the paxm MCP server, and five\nlifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PostToolUse`,\n`PostToolUseFailure`, and `Stop`.\n\nSession bootstrap injects the configured user, agent, and session identity\ntogether with the current local time and time zone. Codex, Claude Code, and Pi\nuse their session-start events; OpenCode performs the same bootstrap before the\nfirst message in a session. If a later user input arrives more than 12 hours\nafter the preceding turn activity, paxm refreshes the local-time context before\nthe agent handles that input.\n\n### OpenCode, Pi, CLI, or MCP\n\nInstall the latest release and run interactive setup. The default SQLite\nprovider makes the adaptor usable without first creating an account or API\nkey.\n\n```bash\ncurl -fsSL https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Freleases\u002Flatest\u002Fdownload\u002Finstall.sh | bash\npaxm setup\npaxm config doctor\n```\n\n`paxm setup` is where the user chooses a stable user ID, providers, and passive\nagent integrations. Selected agents default to IDs such as `codex-todd` and\ncan be renamed during interactive setup. Use up\u002Fdown to move, space to toggle,\nand enter to confirm.\n\nOptional team IDs create explicit durable write profiles such as\n`team-pax-core`; non-interactive setup can pass `--user-id todd --team-id pax-core`.\n\nActive recall skills remain user-installed. SQLite works without an API key;\nremote providers such as Zep, Mem0, MemOS, and OpenViking require connection\ndetails during setup.\n\nSQLite health checks must be allowed to create WAL\u002FSHM files beside the\nconfigured database. A sandbox that can read the database but cannot write its\nparent directory may report SQLite error 14.\n\nUse an isolated writable SQLite path for sandboxed evaluations. The same\nconfiguration may be healthy in the real agent process.\n\nWhen Codex is using the bundled `paxm-memory` plugin, let the plugin own Codex's\nhooks so paxm does not register a duplicate global hook:\n\nWrite and recall a memory:\n\n```bash\npaxm remember --profile ltm --text \"We chose SQLite for the local memory layer\"\npaxm recall --query \"local memory layer\"\npaxm history --days 7\n```\n\nSelect OpenCode during setup to install a global local plugin under\n`~\u002F.config\u002Fopencode\u002Fplugins\u002F`. Select Pi to install its passive extension. Any\nMCP-compatible client can use `paxm mcp serve --agent codex` without passive\nhooks; replace `codex` with the configured client identity.\n\n## SQLite quality preview\n\nSQLite gives a new user a complete local memory loop before they choose or\ndeploy a dedicated memory system. It uses FTS5 and BM25 retrieval with\nturn-level memories and deterministic, query-focused excerpts. Memory ingestion\nand retrieval call no external LLM or embedding service.\n\nIn an initial 30-question LoCoMo agent evaluation, SQLite turn memory answered\n13 questions successfully, compared with 11 for Mem0 product-default.\n\n| Memory arm | Successful answers | Mean token F1 | External models in memory layer |\n| --- | ---: | ---: | --- |\n| paxm SQLite turn memory | 13 \u002F 30 | 0.4211 | None |\n| Mem0 product-default | 11 \u002F 30 | 0.3811 | GPT-5 mini + OpenAI embeddings |\n\nThis is an exploratory result, not an official LoCoMo score or proof that\nSQLite broadly outperforms Mem0. It covers one balanced conversation with\nOpenCode and DeepSeek V4 Flash, using deterministic token F1. See the\n[methodology and limitations](evals\u002Flocomo\u002FREADME.md).\n\n## How it works\n\n![Animated PAXM architecture showing active recall and passive memory routed from AI agents through the adaptor to interchangeable providers](docs\u002Fassets\u002Fpaxm-architecture-animated.gif)\n\nPAXM is a memory adaptor, not another hosted memory service:\n\n```text\nAI agents  ->  CLI \u002F MCP \u002F skills \u002F hooks  ->  paxm  ->  any memory provider\n```\n\nAgents reach paxm in two ways:\n\n| Path | Entry points | Best for |\n| --- | --- | --- |\n| Active | CLI, MCP, skill | Deliberate recall, explicit writes, inspection |\n| Passive | Agent lifecycle hooks | Prompt-time recall and automatic turn capture |\n\nBoth paths use the same runtime and provider router. Filtering, profiles,\nranking, timeouts, telemetry, and provider behavior stay consistent across\nagent surfaces.\n\nPassive writes commit to a local durable queue before provider delivery. Slow\nor unavailable providers retry in the background instead of blocking the\nagent.\n\nPassive recall uses an `800ms` overall budget and `250ms` per-provider budget\nby default. It returns healthy partial results and records downstream\ntimeouts.\n\n### See it in motion\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>One agent surface, any memory provider\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fassets\u002Fpaxm-provider-routing.gif\" width=\"900\" alt=\"Conceptual animation showing AI agents using PAXM to route memory requests across SQLite, OpenViking, Zep, Mem0, and private JSON-RPC providers\">\n\u003C\u002Fp>\n\nPAXM keeps the agent-facing contract stable while profiles choose providers,\nfailure policy, ranking, and timeouts. SQLite is the zero-setup default, not a\nrequired storage backend.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Passive recall and durable background writes\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cbr>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fassets\u002Fpaxm-passive-memory.gif\" width=\"900\" alt=\"Conceptual animation showing PAXM hooks recalling context for an agent and delivering completed turns through a durable background queue\">\n\u003C\u002Fp>\n\nLifecycle hooks recall context before the model request and capture completed\nturns afterward. Writes enter a durable local queue before provider delivery,\nso provider latency does not block the agent.\n\n\u003C\u002Fdetails>\n\nRead the detailed [architecture](docs\u002Farchitecture.md) and\n[provider adapter contract](docs\u002Fprovider-adapter-contract.md).\n\nStored memories distinguish their `origin` (user, agent, session, and turn)\nfrom their visibility `scope`. Providers that advertise attribution support\nmust round-trip both values; see the\n[JSON-RPC provider protocol](docs\u002Fjsonrpc-provider-protocol.md#origin-scope-and-trust).\n\n## Agents and providers\n\n### Agent surfaces\n\n| Agent\u002Fclient | Active | Passive recall | Passive write |\n| --- | :---: | :---: | :---: |\n| Codex | CLI, MCP, skill | Hook | Hook |\n| Claude Code | CLI, MCP, skill | Hook | Hook |\n| Pi | CLI, MCP, skill | Extension | Extension |\n| Any MCP client | MCP tools | — | — |\n\n### Memory providers\n\n| Provider | Mode | Notes |\n| --- | --- | --- |\n| SQLite | Default, built in | Zero-setup turn memory; no API key, LLM, or embeddings |\n| Zep | Built in | User or graph scoped |\n| Mem0 | Built in | Self-hosted REST API |\n| Mem0 Cloud | Built in | Managed Platform API with async v3 writes\u002Fsearch |\n| MemOS | Built in | Self-hosted product API, scoped by memory cube |\n| MemOS Cloud | Built in | Managed OpenMem API with Token authentication |\n| OpenViking | Built in | Self-hosted session extraction and semantic memory search |\n| Custom JSON-RPC | Adapter | Bring an existing or private memory system |\n\nEnable multiple provider instances at once. Recall and write profiles control\nroutes, required or best-effort behavior, ranking weights, thresholds, memory\ntiers, and timeouts.\n\nMem0 score direction is deployment-specific. `score_semantics` defaults to\n`similarity` for backward compatibility; set it to `distance` when the Mem0\nendpoint returns pgvector cosine distance. Paxm cannot infer this from a field\nnamed `score` or `similarity`.\n\nSelf-hosted Mem0 search scope placement is also version-dependent.\n`search_scope_payload: auto` sends `user_id`, `agent_id`, and `run_id` inside\n`filters` first, then retries once with top-level fields only when the server\nreturns a recognized missing-scope compatibility error. Set `top_level` for\nMem0 0.1.117-style servers or `filters` for strict nested-filter deployments.\n\n### Self-hosted OpenViking\n\nOpenViking support connects paxm to a user-operated OpenViking server. Writes\nare recorded through OpenViking sessions and committed for asynchronous memory\nextraction. Recall uses semantic memory search through `\u002Fapi\u002Fv1\u002Fsearch\u002Ffind`.\nThe server URL and optional API key remain in the user's paxm configuration.\n\nRun `paxm setup`, select OpenViking, and provide the self-hosted base URL and\nAPI key. OpenViking can then participate in the same recall and write profiles\nas SQLite or any other provider, with required or best-effort routing and\nprovider-specific timeouts.\n\n## MCP server\n\nRun paxm as a local stdio MCP server:\n\n```bash\npaxm mcp serve --agent codex\n```\n\n```json\n{\n  \"command\": \"paxm\",\n  \"args\": [\"mcp\", \"serve\", \"--agent\", \"codex\"]\n}\n```\n\nThe server exposes four focused tools:\n\n- `paxm_recall`\n- `paxm_remember`\n- `paxm_history`\n- `paxm_config_doctor`\n\nSetup, credential management, hook installation, and backfill stay outside MCP\nso an agent cannot silently take ownership of user configuration.\n\nWrites carry user, agent, and named personal\u002Fteam scope provenance. Recall does\nnot filter by that scope: CLI, MCP, and passive injection label every result\nwith its source scope, while provider-native routing and ACL remain under the\nprovider's control.\n\n## Agent integrations\n\n### Codex plugin\n\nThe Codex plugin packages the paxm setup skill, active memory skill, and native\nCodex hooks. It does not install provider credentials or bypass hook trust.\n\nUse `paxm setup --integration codex-plugin` so only the plugin owns the Codex\nlifecycle hooks.\n\n### Claude Code plugin\n\nThe Claude Code plugin is a first-class integration, not a generic setup shim.\nIt packages skills, an MCP server, and five native lifecycle hooks.\n\nSetup removes only legacy paxm-managed Claude hooks, preserves unrelated hooks,\nand records `claude-plugin` ownership.\n\n### Pi extension\n\nPi support is installed through `paxm setup`. The extension handles passive\nprompt recall and buffers visible user, assistant, and tool events into one\nturn-end memory while excluding thinking blocks.\n\n### OpenCode plugin\n\nOpenCode support is installed through `paxm setup` as a dependency-free global\nplugin. The plugin uses OpenCode's `chat.message` and model-message transform\nhooks for passive recall.\n\nOn `session.idle`, it reads the completed session through the official client\nand writes a durable turn. It captures visible user and assistant text while\nexcluding reasoning and tool payloads.\n\nThe generated plugin lives at `~\u002F.config\u002Fopencode\u002Fplugins\u002Fpaxm.ts`, or below\n`OPENCODE_CONFIG_DIR`\u002F`XDG_CONFIG_HOME` when configured.\n\nSee the complete [configuration guide](docs\u002Fconfig.md) for generated paths,\nevent mappings, profile settings, and uninstall behavior.\n\n## Reliability by default\n\n- Hook acknowledgement waits only for the local queue transaction.\n- Provider delivery is resumable and retried in the background.\n- Optional provider failures do not discard healthy provider results.\n- A stuck provider is contained by its timeout and single-call bulkhead.\n- Write-provider routes default to a 30-second timeout; optional failures remain\n  isolated while required-provider failures are returned to the caller.\n- Recall provenance is stripped before passive writes to prevent memory echo.\n- Exact LTM consolidation limits duplicate accumulation.\n- SQLite preserves completed agent turns with explicit session, turn, and time\n  boundaries.\n- Telemetry stores hashes and lengths by default, not raw recall queries.\n\nHistorical imports are also resumable:\n\n```bash\npaxm backfill scan --agent codex --before 2026-07-09\npaxm backfill run --agent codex --provider mem0-company --background\npaxm backfill status --agent codex --provider mem0-company\n```\n\n## Performance\n\nBenchmarks use runtime-generated temporary datasets modeled after real passive\nagent workloads; no benchmark corpus is committed to the repository.\n\nOn an Apple M4 reference machine:\n\n| Workload | Adapter latency |\n| --- | ---: |\n| 128 KiB SQLite write | 1.84 ms |\n| 2 MiB SQLite write | 14.31 ms |\n| 10-item \u002F 1.25 MiB batch | 12.36 ms |\n| Recall from 100,000 short memories | 0.54 ms |\n| Recall from 10,000 x 32 KiB memories | 0.61 ms |\n\nThese numbers measure the adapter, not end-to-end agent response time. See the\ndatasets, commands, allocations, and machine details in\n[SQLite adapter benchmarks](docs\u002Fbenchmarks.md).\n\n## Evaluation\n\npaxm separates deterministic regression suites from paid, real-agent quality\nevaluations. CI protects runtime behavior; opt-in benchmarks measure whether\nmemory helps an agent answer correctly.\n\nThe repository includes deterministic production-path evaluations:\n\n```bash\ngo run .\u002Fcmd\u002Fpaxm eval run --suite evals\u002Fbaseline\ngo run .\u002Fcmd\u002Fpaxm eval run --suite evals\u002Fconversation-write\n```\n\n- A 100-case retrieval suite reports recall@K, precision@K, MRR, false-positive\n  rate, latency, and category-level results.\n- A 50-case conversation-to-write suite checks admission, recall, forbidden\n  fragments, metadata preservation, and adapter contract behavior.\n\nCI runs unit tests, vet, the retrieval report, and the adapter write contract on\nevery push to `main` and every pull request.\n\nThe opt-in [LoCoMo agent benchmark](evals\u002Flocomo\u002FREADME.md) exercises real\nOpenCode sessions and production MCP or passive recall.\n\nThe [cross-agent benchmark](evals\u002Fcross-agent\u002FREADME.md) tests whether one\nagent's experience helps another avoid the same failure.\n\nPaid agent evaluations are never run in ordinary CI. Their reports separate\nmemory-layer cost from answering-model cost and state their evidence limits.\n\n## Documentation\n\n| Guide | Contents |\n| --- | --- |\n| [中文使用指南](docs\u002FREADME.zh-CN.md) | 中文快速开始、agent 接入、provider 配置与排障 |\n| [中文 JSON-RPC 接入指南](docs\u002Fjsonrpc-provider-protocol.zh-CN.md) | 自定义 memory provider 的协议、实现与一致性验证 |\n| [Configuration](docs\u002Fconfig.md) | Providers, profiles, agents, hooks, telemetry |\n| [Architecture](docs\u002Farchitecture.md) | Runtime modules and data flow |\n| [Provider contract](docs\u002Fprovider-adapter-contract.md) | Implementing a memory adapter |\n| [Benchmarks](docs\u002Fbenchmarks.md) | Passive workload datasets and results |\n| [LoCoMo evaluation](evals\u002Flocomo\u002FREADME.md) | Real-agent memory quality methodology |\n| [Release guide](docs\u002Frelease.md) | Builds, checksums, tags, and publishing |\n| [Roadmap](docs\u002Froadmap.md) | Current product direction |\n\n## Community\n\n- Ask setup questions, share successful workflows, and discuss early ideas in\n  [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Fdiscussions).\n- Report reproducible bugs or request a demand-backed integration through the\n  repository's structured [issue forms](https:\u002F\u002Fgithub.com\u002Fpax-beehive\u002Fpaxm\u002Fissues\u002Fnew\u002Fchoose).\n- Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a substantial change.\n- Report suspected vulnerabilities privately according to\n  [SECURITY.md](SECURITY.md).\n\n## Development\n\n```bash\ngo test .\u002F...\ngo vet .\u002F...\ngo build -o \u002Ftmp\u002Fpaxm .\u002Fcmd\u002Fpaxm\n\u002Ftmp\u002Fpaxm --config \u002Ftmp\u002Fpaxm-dev\u002Fconfig.yaml setup --force\n```\n\n## Releases\n\nReleases cover macOS, Linux, and Windows on `amd64` and `arm64`. Published\narchives include `SHA256SUMS`, and the installer verifies the selected archive\nbefore replacing the binary.\n\nSee the [release guide](docs\u002Frelease.md) for validation, tagging, asset, and\ninstaller smoke-test requirements.\n","PAXM 是一个面向编程智能体的持久化、供应商中立的记忆存储系统，支持 Codex、Claude Code、OpenCode、Pi 和 MCP 等编码代理无缝共享和复用项目上下文。它基于 SQLite 本地优先设计，无需 API 密钥、嵌入模型或云端依赖，提供主动记忆（显式存取）与被动记忆（自动捕获对话轮次）双模式，并可通过 JSON-RPC 接入 Zep、Mem0 等外部记忆服务。适用于本地开发环境下的多代理协同场景，帮助开发者避免在每次会话中重复解释架构决策、部署规范等关键上下文。",2,"2026-07-16 02:30:07","CREATED_QUERY"]