{"_id":"@anneal-memory/paperclip-plugin","_rev":"2-dba06bc4dc667fce5d3eb9a056f45d1d","name":"@anneal-memory/paperclip-plugin","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@anneal-memory/paperclip-plugin","version":"0.0.1","keywords":["paperclip","paperclip-plugin","anneal-memory","ai-agents","memory","mcp"],"author":{"name":"Phill Clapham","email":"phill@claphamdigital.com"},"license":"MIT","_id":"@anneal-memory/paperclip-plugin@0.0.1","maintainers":[{"name":"phillipclapham","email":"me@phillipclapham.com"}],"homepage":"https://github.com/phillipclapham/anneal-memory-paperclip-plugin","bugs":{"url":"https://github.com/phillipclapham/anneal-memory-paperclip-plugin/issues"},"dist":{"shasum":"451018e9ee489314a0ed5029fe8ba7e0af8a6c97","tarball":"https://registry.npmjs.org/@anneal-memory/paperclip-plugin/-/paperclip-plugin-0.0.1.tgz","fileCount":23,"integrity":"sha512-CkVrZ3uPDVxfA4pQnIJADvGAXfxWVikqUtusaG5Xn4SMH71hlrB1ZfwiYw/1woMddoGEN+O2FHwprwhL3DGm2w==","signatures":[{"sig":"MEUCIQD32N9uIAXvNqFV4jt9OKok/5Oe1uK8Dm6Iqa/B1lS7/wIgUtq1CDwiVpotBWTKRTsldFqsr2taEzFVa9ZJB20gN7I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69666},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":"./dist/index.js"},"gitHead":"b569da96965f9fe411ca58e4d23cc5befef0b826","private":false,"scripts":{"build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"phillipclapham","email":"me@phillipclapham.com"},"repository":{"url":"git+https://github.com/phillipclapham/anneal-memory-paperclip-plugin.git","type":"git"},"_npmVersion":"11.12.1","description":"anneal-memory as a Paperclip plugin — first-class four-layer memory (episodic + continuity + Hebbian + limbic) with immune system. Wraps the anneal-memory Python MCP server as a per-agent subprocess.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"@paperclipai/plugin-sdk":"2026.512.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.3","@types/node":"^24.6.0"},"paperclipPlugin":{"worker":"./dist/worker.js","manifest":"./dist/manifest.js"},"_npmOperationalInternal":{"tmp":"tmp/paperclip-plugin_0.0.1_1778690917403_0.5214466282668289","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@anneal-memory/paperclip-plugin","version":"0.0.2","description":"anneal-memory as a Paperclip plugin — first-class four-layer memory (episodic + continuity + Hebbian + limbic) with immune system. Wraps the anneal-memory Python MCP server as a per-agent subprocess.","type":"module","private":false,"author":{"name":"Phill Clapham","email":"phill@claphamdigital.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/phillipclapham/anneal-memory-paperclip-plugin.git"},"homepage":"https://github.com/phillipclapham/anneal-memory-paperclip-plugin","keywords":["paperclip","paperclip-plugin","anneal-memory","ai-agents","memory","mcp"],"exports":{".":"./dist/index.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","paperclipPlugin":{"manifest":"./dist/manifest.js","worker":"./dist/worker.js"},"engines":{"node":">=20"},"scripts":{"build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run clean && npm run build"},"dependencies":{"@paperclipai/plugin-sdk":"2026.512.0"},"devDependencies":{"@types/node":"^24.6.0","typescript":"^5.7.3"},"gitHead":"e595f62bbbca2d528ace460e19f1c4dc994603ea","_id":"@anneal-memory/paperclip-plugin@0.0.2","bugs":{"url":"https://github.com/phillipclapham/anneal-memory-paperclip-plugin/issues"},"_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Kj/3eTBY2Zx7rhD1DZ2GGS1wvWyFvI1J1drqt0IBFchhKomSZwGcqfu7/NQbN8tE5G90AwQgk+rw1UyF66pbHg==","shasum":"09ed8e6aaf51fe8dd796fb0571b9cf6c96e15948","tarball":"https://registry.npmjs.org/@anneal-memory/paperclip-plugin/-/paperclip-plugin-0.0.2.tgz","fileCount":23,"unpackedSize":78258,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC24k7SX+XXH1yxkD+HXGF51Gk2XxveP4kWJQwDBYR9sAIgF88ZsmDRe6gaQjZqU2eRmlYH8M5rtDKn9Uqf2ffvECc="}]},"_npmUser":{"name":"phillipclapham","email":"me@phillipclapham.com"},"directories":{},"maintainers":[{"name":"phillipclapham","email":"me@phillipclapham.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/paperclip-plugin_0.0.2_1778712812883_0.7439604385304306"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T16:48:37.342Z","modified":"2026-05-13T22:53:33.247Z","0.0.1":"2026-05-13T16:48:37.611Z","0.0.2":"2026-05-13T22:53:33.133Z"},"bugs":{"url":"https://github.com/phillipclapham/anneal-memory-paperclip-plugin/issues"},"author":{"name":"Phill Clapham","email":"phill@claphamdigital.com"},"license":"MIT","homepage":"https://github.com/phillipclapham/anneal-memory-paperclip-plugin","keywords":["paperclip","paperclip-plugin","anneal-memory","ai-agents","memory","mcp"],"repository":{"type":"git","url":"git+https://github.com/phillipclapham/anneal-memory-paperclip-plugin.git"},"description":"anneal-memory as a Paperclip plugin — first-class four-layer memory (episodic + continuity + Hebbian + limbic) with immune system. Wraps the anneal-memory Python MCP server as a per-agent subprocess.","maintainers":[{"name":"phillipclapham","email":"me@phillipclapham.com"}],"readme":"# @anneal-memory/paperclip-plugin\n\nFirst-class four-layer memory for [Paperclip](https://github.com/paperclipai/paperclip) agents, wrapping the [anneal-memory](https://github.com/phillipclapham/anneal-memory) Python MCP server.\n\n**Status:** v0.0.1 — full stack end-to-end validated against Paperclip 2026.512.0 on May 13, 2026 across 4 named load tests (B1/B2/B3/B1.5) plus an ANN-13 v2 4-wrap sustained-load sequence demonstrating immune-system demotion and closed-loop learning in production (see [In-production validation](#in-production-validation)). 5 upstream Paperclip findings filed day-one (see [Filed upstream](#filed-upstream)). Working but requires an upstream Paperclip patch + a one-time agent-instructions edit. See [Known Limitations](#known-limitations) before installing.\n\n---\n\n## ⚠ Read this before installing\n\n**Two things must be done outside this package for the plugin to work end-to-end:**\n\n### 1. `anneal-memory` must be on PATH\n\nThe plugin spawns the [anneal-memory](https://github.com/phillipclapham/anneal-memory) Python MCP server as a child process. If `anneal-memory` is not resolvable via PATH, the plugin worker will start but every tool call will fail at child-spawn time.\n\nInstall once globally:\n```bash\nuv tool install anneal-memory\n# Verify:\nwhich anneal-memory && anneal-memory --version\n```\n\nAlternative paths (pipx, virtualenv) work too; override via the plugin's `mcpCommand` config field.\n\n### 2. Paperclip 2026.512.0 has an upstream tool-registry bug that prevents executeTool from reaching plugin workers\n\nSymptom: every plugin tool call returns `Cannot execute tool \"<name>\" — worker for plugin \"<id>\" is not running` even though the worker process is running and tools are registered.\n\nRoot cause: `plugin-loader.js` calls `toolDispatcher.registerPluginTools(pluginKey, manifest)` without passing the plugin's UUID dbId. The tool registry then defaults `pluginDbId` to `pluginKey` (the short manifest id). When `executeTool` checks `workerManager.isRunning(tool.pluginDbId)`, it looks up the short id in a workers map keyed by UUID → false → 502.\n\nFiled upstream: **[paperclipai/paperclip#5916](https://github.com/paperclipai/paperclip/issues/5916)** — see that issue for the complete bug report, two-line patch, and reproduction steps. The same detail is also captured in [UPSTREAM_PAPERCLIP_FINDINGS.md](./UPSTREAM_PAPERCLIP_FINDINGS.md) for offline reference. Until Paperclip ships a fix, this plugin requires the patch from issue #5916 applied to the installed `@paperclipai/server` package.\n\n### 3. Plugin tools aren't auto-discovered by `claude_local` agents\n\nPaperclip's `claude_local` adapter does NOT inject plugin tools into Claude Code's runtime tool set. Even after the upstream patch lands, the agent has to be told about the plugin's tools via its instructions bundle. See [Teaching Your Agent About anneal-memory](#teaching-your-agent-about-anneal-memory) below.\n\n---\n\n## What it gives Paperclip agents\n\n- **Episodic store** — typed episodes (`observation` / `decision` / `tension` / `question` / `outcome` / `context`) with SHA-256 hash-chained audit trail\n- **Continuity file** — compressed agent memory loaded at session start, citation-validated at compression time\n- **Hebbian associations** — co-citation links between episodes, decayed over time\n- **Limbic affective tagging** — functional-state modulation of association strength\n- **Immune system** — citation-gaming detection + active demotion of ungrounded graduations\n- **Per-agent isolation** — each Paperclip agent gets its own SQLite store at `<storeBasePath>/<agentId>/memory.db`\n\n## In-production validation\n\nThe architectural claim is that the four-layer memory + immune system\nproduces **compression-with-intelligence** — memory that gets smarter\n(not just longer) as evidence accumulates. The ANN-13 v2 4-wrap sequence\non May 13, 2026 demonstrates this in production runtime:\n\n| Wrap | Continuity size | What happened |\n|---|---|---|\n| #2 | 6,373 chars | New patterns surfaced from heartbeat #1 evidence. |\n| **#3** | **5,804 chars** | **Immune system demoted a bad self-citation. Continuity SHRANK 569 chars.** Agent re-examined a pattern it had graduated earlier, ruled the supporting evidence didn't hold, removed the graduation. |\n| **#4** | 7,027 chars | **Closed-loop learning.** Agent codified the wrap-#3 demotion lesson as a new pattern AND applied it on the next graduation evaluation. Memory got smarter because it corrected itself. |\n\nThis is the architecturally distinctive behavior versus flat-retrieval\nmemory substrates: graduation + active demotion + structurally-enforced\ncompression produce process evolution, not bloat-instead-of-smart.\n\nThree additional named load tests passed earlier the same day:\n\n- **B1 — single-agent wrap cycle (Claude C-level): PASS.** Full\n  wrap completed autonomously with 4-section FlowScript continuity;\n  agent surfaced a novel runtime quirk (Finding #5) as a pattern\n  unprompted.\n- **B2 — multi-agent C-level coordination: PASS.** Parallel CMO + CTO\n  agents; each SQLite store contained only its own episodes. Direct\n  refutation of the global-continuity-fills-too-fast failure mode.\n- **B3 — Codex C-level wrap cognition: PASS-WITH-NUANCE.** Codex\n  executed valid wrap-class cognition (4 min vs Claude's 1 min, more\n  methodical, one tombstone self-correction). Refutes strong \"Codex\n  can't run wraps\" claim; texture difference is real, mechanical\n  capability holds.\n- **B1.5 — cold-session memory carry-forward: PASS.** Agent on a\n  cold-context session read its own continuity, refused to redo B1,\n  proposed B2-style continuity-merge as next test, surfaced a novel\n  meta-pattern (write-path vs read-path test taxonomy).\n\nFull receipt in [CHANGELOG.md](./CHANGELOG.md).\n\n## Architecture\n\n```\nPaperclip host (Node.js)\n    ↕  JSON-RPC over stdio (Paperclip plugin protocol)\n@anneal-memory/paperclip-plugin (this package — TS worker)\n    ↕  JSON-RPC over stdio (MCP 2024-11-05)\nanneal-memory Python MCP server (per-agent subprocess)\n    ↕  Python library calls\nSQLite store + continuity markdown file\n```\n\nOne MCP child process per Paperclip agent, lazy on first tool call. The pool reuses bridges within a worker lifetime and installs process-level shutdown handlers so MCP children don't become orphans if the parent dies.\n\n## Tools registered\n\nAll six anneal-memory MCP tools surface as Paperclip agent tools under the `anneal-memory:` namespace:\n\n| Tool | Purpose |\n|---|---|\n| `anneal-memory:record` | Record a typed episode (observation/decision/tension/question/outcome/context) |\n| `anneal-memory:recall` | Query episodes — time / type / source / keyword / limit filters |\n| `anneal-memory:prepare_wrap` | Get compression package at session boundary; mints a `wrap_token` |\n| `anneal-memory:save_continuity` | Validate + save compressed continuity, with structure / citation-grounding / citation-gaming checks |\n| `anneal-memory:delete_episode` | GDPR-grade delete by episode ID with tombstone preservation |\n| `anneal-memory:status` | Memory health metrics (counts, wrap state, Hebbian density, audit chain) |\n\n## Requirements\n\n- Node.js 20+\n- Paperclip v2026.512.0 or later (with [upstream patch](./UPSTREAM_PAPERCLIP_FINDINGS.md) applied)\n- `anneal-memory` Python MCP server installed and reachable via PATH\n\n## Quickstart\n\nFive steps to a working install on Paperclip 2026.512.0. Will collapse\nto a one-liner once Paperclip ships the [#5916](https://github.com/paperclipai/paperclip/issues/5916)\npatch upstream.\n\n### 1. Install `anneal-memory` (Python MCP server) globally\n\nThe plugin spawns this as a child process per agent. Must be on PATH.\n\n```bash\nuv tool install anneal-memory\n# Verify:\nwhich anneal-memory && anneal-memory --version\n```\n\nAlternative paths (`pipx`, virtualenv) work too; override via the plugin's\n`mcpCommand` config field.\n\n### 2. Apply the upstream #5916 patch to your Paperclip server\n\nRequired until the patch lands upstream. Two-line fix in the compiled JS\nof your installed `@paperclipai/server` package:\n\n```diff\n--- a/dist/services/plugin-tool-dispatcher.js  (~line 210)\n+++ b/dist/services/plugin-tool-dispatcher.js\n-    registerPluginTools(pluginId, manifest) {\n-        registry.registerPlugin(pluginId, manifest);\n+    registerPluginTools(pluginId, manifest, pluginDbId) {\n+        registry.registerPlugin(pluginId, manifest, pluginDbId);\n     },\n\n--- a/dist/services/plugin-loader.js  (~line 1151)\n+++ b/dist/services/plugin-loader.js\n-                toolDispatcher.registerPluginTools(pluginKey, manifest);\n+                toolDispatcher.registerPluginTools(pluginKey, manifest, pluginId);\n```\n\nThe `pluginId` variable is already in scope at the call site. No new\nlookups or async paths required.\n\nFull reproduction steps + line-number context in\n[#5916](https://github.com/paperclipai/paperclip/issues/5916) and\n[UPSTREAM_PAPERCLIP_FINDINGS.md](./UPSTREAM_PAPERCLIP_FINDINGS.md).\n\nRestart your Paperclip server after applying the patch.\n\n### 3. Install the plugin\n\nFrom a local checkout (the canonical path while Paperclip's published\ninstall command awaits #5916):\n\n```bash\ngit clone https://github.com/phillipclapham/anneal-memory-paperclip-plugin\ncd anneal-memory-paperclip-plugin\nnpm install && npm run build\n\n# From your Paperclip instance host:\ncurl -X POST http://127.0.0.1:3100/api/plugins/install \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"packageName\":\"/absolute/path/to/anneal-memory-paperclip-plugin\",\"isLocalPath\":true}'\n```\n\nVerify the plugin loaded:\n\n```bash\ncurl http://127.0.0.1:3100/api/plugins\n# Look for: status: \"ready\", lastError: null, tools: 6\n```\n\n### 4. Teach your agent about the plugin tools\n\nPaperclip's `claude_local` adapter does not auto-discover plugin tools in\nv2026.512.0. Drop the `TOOLS.md` template into your agent's instructions\nbundle:\n\n```bash\ncp TOOLS.md ~/.paperclip/agents/<your-agent>/instructions/TOOLS.md\n```\n\nThe template is the agent's instructions verbatim — operator-facing\nintro at the top, agent-bound content below the divider. No editing\nrequired.\n\n### 5. Verify end-to-end\n\nHave your agent call `anneal-memory:status`. Expected response shape:\n\n```json\n{\n  \"episode_count\": 0,\n  \"continuity_chars\": 0,\n  \"wrap_state\": \"ready\",\n  \"hebbian_density\": 0,\n  \"audit_chain_ok\": true\n}\n```\n\nIf you see this, the full stack — agent → Paperclip dispatcher → plugin\nworker → MCP child → SQLite store — is working. Memory health check\npassed. Begin recording episodes; call `prepare_wrap` + `save_continuity`\nat session boundaries to graduate patterns.\n\n---\n\n**Future state** (once Paperclip ships #5916 upstream): steps 2 and 3\ncollapse to a single line.\n\n```bash\nuv tool install anneal-memory\npaperclipai plugin install @anneal-memory/paperclip-plugin\ncp TOOLS.md ~/.paperclip/agents/<your-agent>/instructions/TOOLS.md\n```\n\nStep 4 may also become unnecessary if Paperclip adds plugin-tool\nauto-discovery for `claude_local`.\n\n## Config\n\n| Key | Default | Description |\n|---|---|---|\n| `mcpCommand` | `anneal-memory` | Path / command name for the Python MCP server executable. Override for `uvx`, `pipx`, or virtualenv installs. |\n| `storeBasePath` | `~/.paperclip/data/plugins/anneal-memory/stores` | Base directory for per-agent SQLite stores. Each Paperclip agent gets a subdirectory: `<storeBasePath>/<agentId>/memory.db`. |\n| `autoRecordEvents` | `false` | (v0.0.1: declared but not yet implemented — see [Known Limitations](#known-limitations).) When implemented, will auto-record Paperclip events as `observation` episodes. |\n\n## Teaching Your Agent About anneal-memory\n\nIn Paperclip 2026.512.0, plugin tools are exposed on\n`/api/plugins/tools/execute` but the `claude_local` adapter does not\ninject them into Claude Code's tool set. The agent must be told the\ntools exist and how to call them.\n\nDrop-in template lives at **[`TOOLS.md`](./TOOLS.md)**. Copy into your\nagent's instructions bundle:\n\n```bash\ncp TOOLS.md ~/.paperclip/agents/<your-agent>/instructions/TOOLS.md\n```\n\nThe template is the agent's instructions verbatim — operator-facing\nintro at the top, agent-bound content below the divider. No editing\nrequired.\n\n(This manual injection step will likely be unnecessary in future\nPaperclip versions once the project addresses plugin-tool\nauto-discovery for the `claude_local` adapter.)\n\n## Known Limitations\n\n### Methodology-under-Paperclip-runtime: validated single-cycle, sustained-load open\n\n**Read this carefully before relying on the plugin in production.** Today's\nload testing (May 13, 2026) updated the validation status:\n\n**What v0.0.1 has validated** under Paperclip 2026.512.0 runtime:\n\n- Storage layer — install/register/dispatch/execute path clean,\n  per-agent SQLite isolation verified, audit chain holds.\n- **Wrap discipline + pattern graduation** — B1 single-agent + B3 Codex\n  wrap cycles both completed with structurally-correct 4-section\n  FlowScript continuity; graduation criteria fired correctly.\n- **Immune system in production** — ANN-13 v2 wrap #3 demoted a bad\n  self-citation autonomously; continuity SHRANK by 569 chars (see\n  [In-production validation](#in-production-validation)).\n- **Closed-loop learning** — ANN-13 v2 wrap #4 codified the demotion\n  lesson as a pattern and applied it on the next graduation.\n- **Multi-agent autonomous coordination** — B2 CMO + CTO parallel\n  agents maintained per-store isolation under Paperclip's multi-agent\n  coordination semantics.\n- **Cross-substrate wrap cognition** — B3 confirmed Codex can run\n  wrap-class cognition on the plugin contract (texture difference vs.\n  Claude exists; mechanical capability holds).\n- **Cold-session carry-forward** — B1.5 agent on a fresh context read\n  its own continuity and refused to redo prior work; wrap-thrash\n  disconfirmed at session-cold boundary.\n\n**What v0.0.1 does NOT yet validate:** sustained operational load over\ndays and weeks. Heartbeat cadence over many cycles, day-over-day\ncontinuity carry-forward at production scale, multi-week pattern\naccumulation, multi-tenant coordination at scale. Single-cycle\nmethodology execution under Paperclip's runtime now has empirical\nreceipts; sustained-load is the remaining hypothesis.\n\nSpecific Paperclip semantic blockers — current status:\n\n- **Wrap-thrash from heartbeat-driven wrap cadence.** DISCONFIRMED in\n  single-cycle scope (B1 + B1.5). Open at sustained-load scope.\n- **Mid-wrap agent restart.** Hypothetical — storage-layer 2PC handles\n  partial commits; runtime-abort behavior in production not tested.\n- **Tool budget exhaustion mid-wrap.** DISCONFIRMED in single-cycle\n  scope; B1/B2/B3 wraps all completed within heartbeat budgets at\n  observed tool-call counts.\n- **Double-tracking drift.** OPEN. Paperclip tracks coordination via\n  issues/comments; plugin tracks via episodes. Canonical correspondence\n  still ad hoc.\n- **Workspace state authority conflict.** OPEN. `project_workspaces`\n  and per-agent plugin data dir are two filesystem authorities for\n  \"agent state.\" Long-run drift potential.\n- **Model substrate axis.** CONFIRMED real (and orthogonal to the plugin).\n  Codex executes mechanical wrap cognition but with detectable texture\n  difference vs. Claude (more methodical, less novel-pattern surfacing).\n  Operator should assign Claude Sonnet or Opus to wrap-executing C-level\n  roles; the plugin enforces nothing about this.\n\n**Position to hold publicly:** plugin is mechanical infrastructure\nvalidated AND single-cycle methodology execution under Paperclip\nruntime is validated, including immune system + closed-loop learning\nin production. Sustained-load behavior over days/weeks remains the\nopen empirical question. The first operator to deploy at production\nscale is the v0.1 validation gate. If you surface specific failure\nmodes, please open an issue with reproduction steps — that data IS\nthe v0.1 spec.\n\n### Other v0.0.1 boundaries (less critical, tracked for v0.1)\n\n1. **`autoRecordEvents` config flag is declared but not yet wired** — when\n   set, no `onEvent` handler is currently registered. Manifest field will be\n   honored in v0.1.\n2. **`onHealth` is shallow** — returns \"ok\" whenever the bridge pool exists.\n   Does not probe per-agent MCP children for actual responsiveness.\n3. **`validateConfig` RPC is not implemented** — bad config surfaces at first\n   tool call instead of plugin install.\n4. **Paperclip version pinned exact** to `2026.512.0`. Plugin will need\n   re-validation against subsequent Paperclip releases (CalVer).\n5. **No retry policy on the first tool call after MCP child auto-restart** —\n   the auto-restart mechanism is in place (default 3 attempts, exponential\n   backoff from 1s) but tool calls that happen during the restart window\n   will fail. v0.1 will queue calls during recovery windows.\n\n## Filed upstream\n\nFive Paperclip findings surfaced during plugin development and load\ntesting, all filed against [paperclipai/paperclip](https://github.com/paperclipai/paperclip):\n\n- **[#5916](https://github.com/paperclipai/paperclip/issues/5916)** —\n  Plugin tool execution always 502s because `registerPluginTools`\n  drops the plugin's UUID `dbId`. Two-line patch inlined in the issue.\n  **Required** for this plugin to work end-to-end. Detailed reproduction\n  steps + offline reference in [UPSTREAM_PAPERCLIP_FINDINGS.md](./UPSTREAM_PAPERCLIP_FINDINGS.md).\n- **[#5932](https://github.com/paperclipai/paperclip/issues/5932)** —\n  `acpx_local` adapter ships without the `claude-agent-acp` runtime\n  dependency. Workaround: use `claude_local` adapter.\n- **[#5933](https://github.com/paperclipai/paperclip/issues/5933)** —\n  `PAPERCLIP_PROJECT_ID` env var sometimes empty/unset. Agent\n  self-recovers via cwd-path parsing.\n- **[#5935](https://github.com/paperclipai/paperclip/issues/5935)** —\n  Heartbeat wake fires on agent's own issue comments, producing a\n  sub-minute self-perpetuating wake-loop. Workaround: agents record\n  state to plugin memory only, operators read state out-of-band, no\n  agent self-comments on assigned issues.\n- **[#5937](https://github.com/paperclipai/paperclip/issues/5937)** —\n  Auto-recovery flow creates sibling issues whose run contexts override\n  issue-level operator protocol (e.g., \"operator owns close\" rules).\n\nFull triage notes + load-test context in\n[UPSTREAM_PAPERCLIP_FINDINGS.md](./UPSTREAM_PAPERCLIP_FINDINGS.md) and\n[CHANGELOG.md](./CHANGELOG.md).\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck       # tsc --noEmit\nnpm run build           # tsc → dist/\nnode test/smoke.mjs     # end-to-end smoke test against real anneal-memory subprocess\n```\n\nThe smoke test exercises the bridge end-to-end against a real Python\nsubprocess without involving Paperclip:\n\n- bridge start + initialize handshake\n- record / recall / status round-trip\n- prepare_wrap → save_continuity full wrap cycle with token validation\n- BridgePool multi-agent isolation (separate subprocesses, no cross-store leakage)\n- tool-level error conversion (`isError: true` → Promise rejection)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}