{"_id":"@astragenie/astramem-client","_rev":"3-f1086a52f8038d9707875b9ac1524e13","name":"@astragenie/astramem-client","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@astragenie/astramem-client","version":"0.1.0","license":"MIT","_id":"@astragenie/astramem-client@0.1.0","maintainers":[{"name":"heroboec","email":"shishkosv@gmail.com"}],"homepage":"https://github.com/astragenie/plugins-common#readme","bugs":{"url":"https://github.com/astragenie/plugins-common/issues"},"dist":{"shasum":"3afaf1e7801d44e36e3284eb65d4aea1ccea0776","tarball":"https://registry.npmjs.org/@astragenie/astramem-client/-/astramem-client-0.1.0.tgz","fileCount":18,"integrity":"sha512-yz4d3BhxrI/vLmvAHePsyKjBn9LVpeH29MjIzy+IvVwuv3d9AHEHhPhhvL6KlTlcsrVhKR2+1C6z+jBOE8QThA==","signatures":[{"sig":"MEUCIQCbKZVy7VZTq3zAgJztFA15hLMEs6uKHDHffPel0C/5jwIgFEcd5+GAs908/WohBGr5t9P/+MZ8qStUpJqhZ9zOJN8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@astragenie%2fastramem-client@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":30524},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.3.0","node":">=22.6.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"381ea138f533e2a3085892746c39b02bcde51e34","scripts":{"lint":"biome check src tests","test":"bun test --parallel --timeout 30000 tests/","build":"tsc -p tsconfig.build.json","format":"biome format --write src tests","typecheck":"tsc --noEmit","format:check":"biome format src tests","prepublishOnly":"bun run build"},"_npmUser":{"name":"heroboec","email":"shishkosv@gmail.com"},"repository":{"url":"git+https://github.com/astragenie/plugins-common.git","type":"git","directory":"packages/astramem-client"},"_npmVersion":"10.9.8","description":"Shared fail-silent client seam for the astramem memory plugin — provider resolution (dep-mode selector, dep-mode local/saas probe, runtime plugin-root discovery) plus wallclock-capped remember/recall calls. Extracted from dev-team's astramem-provider and ","directories":{},"_nodeVersion":"22.23.1","_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.1.0","typescript":"^5.5.0","@types/node":"^22.0.0","@biomejs/biome":"^1.9.0"},"peerDependencies":{"@astragenie/astramem-plugin":">=0.6.0"},"peerDependenciesMeta":{"@astragenie/astramem-plugin":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/astramem-client_0.1.0_1783414130955_0.2037491973037342","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@astragenie/astramem-client","version":"0.2.0","license":"MIT","_id":"@astragenie/astramem-client@0.2.0","maintainers":[{"name":"heroboec","email":"shishkosv@gmail.com"}],"homepage":"https://github.com/astragenie/plugins-common#readme","bugs":{"url":"https://github.com/astragenie/plugins-common/issues"},"dist":{"shasum":"fcf8d13db8406ed68af56ac4bc1c4c21d9237800","tarball":"https://registry.npmjs.org/@astragenie/astramem-client/-/astramem-client-0.2.0.tgz","fileCount":30,"integrity":"sha512-5cmiPMgHKeudFQN0TmHAv4ybcZX7SWsKo12UrfThiKbTK7Nx/JjPtr7aFcpWkABc8/n5Jil1YQ+vf72mfzmKcg==","signatures":[{"sig":"MEUCIHV1Rv0K3t3XfNKxQSPk3oeyuSAYHLH5+j33ZWOcy17GAiEAwQFDXyvhDuTKl5hWAvCm6zVwXD8lDKmbOaxlBMZax1I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@astragenie%2fastramem-client@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":84306},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.3.0","node":">=22.6.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"b6190395d742f1b1a269e59cc72e9716196812b1","scripts":{"lint":"biome check src tests","test":"bun test --parallel --timeout 30000 tests/","build":"tsc -p tsconfig.build.json","format":"biome format --write src tests","typecheck":"tsc --noEmit","format:check":"biome format src tests","prepublishOnly":"bun run build"},"_npmUser":{"name":"heroboec","email":"shishkosv@gmail.com"},"repository":{"url":"git+https://github.com/astragenie/plugins-common.git","type":"git","directory":"packages/astramem-client"},"_npmVersion":"10.9.8","description":"Shared fail-silent client seam for the astramem memory plugin — provider resolution (dep-mode selector, dep-mode local/saas probe, runtime plugin-root discovery) plus wallclock-capped remember/recall calls — plus AstramemDaemonClient, a typed direct HTTP ","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"^1.1.0","typescript":"^5.5.0","@types/node":"^22.0.0","@biomejs/biome":"^1.9.0"},"peerDependencies":{"@astragenie/astramem-plugin":">=0.6.0"},"peerDependenciesMeta":{"@astragenie/astramem-plugin":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/astramem-client_0.2.0_1783685826632_0.0450601076064201","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@astragenie/astramem-client","version":"0.3.0","description":"Shared fail-silent client seam for the astramem memory plugin — provider resolution (dep-mode selector, dep-mode local/saas probe, runtime plugin-root discovery) plus wallclock-capped remember/recall calls — plus AstramemDaemonClient, a typed direct HTTP ","license":"MIT","repository":{"type":"git","url":"git+https://github.com/astragenie/plugins-common.git","directory":"packages/astramem-client"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"engines":{"node":">=22.6.0","bun":">=1.3.0"},"scripts":{"lint":"biome check src tests","format":"biome format --write src tests","format:check":"biome format src tests","typecheck":"tsc --noEmit","build":"tsc -p tsconfig.build.json","prepublishOnly":"bun run build","test":"bun test --parallel --timeout 30000 tests/"},"publishConfig":{"registry":"https://registry.npmjs.org/","access":"public"},"peerDependencies":{"@astragenie/astramem-plugin":">=0.6.0"},"peerDependenciesMeta":{"@astragenie/astramem-plugin":{"optional":true}},"devDependencies":{"@biomejs/biome":"^1.9.0","@types/node":"^22.0.0","bun-types":"^1.1.0","typescript":"^7.0.2"},"_id":"@astragenie/astramem-client@0.3.0","gitHead":"9a94b89c733dcb621afa79b5f999e3ff498b44dc","bugs":{"url":"https://github.com/astragenie/plugins-common/issues"},"homepage":"https://github.com/astragenie/plugins-common#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-bdrBVUt53MbalthyhyH4tYUbw2Q7RQ2S2so5s5VXHuxR36Q2s5ui+bm+ZcZGVNY2demOJfPY82ge0viDuKjkbQ==","shasum":"f7e33523a16e3bb469391498c821e45e6f6480dd","tarball":"https://registry.npmjs.org/@astragenie/astramem-client/-/astramem-client-0.3.0.tgz","fileCount":34,"unpackedSize":95269,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@astragenie%2fastramem-client@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGDEGZESQpIJtXcxTSyUObXFy1VrBv916Y7g7L+tNdZpAiAn7T2NsSHoROqyal9SNXugrx/KxW5sD/ubTqrPL+WzZg=="}]},"_npmUser":{"name":"heroboec","email":"shishkosv@gmail.com"},"directories":{},"maintainers":[{"name":"heroboec","email":"shishkosv@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/astramem-client_0.3.0_1784071312573_0.6492698320436738"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-07T08:48:50.790Z","modified":"2026-07-14T23:21:53.031Z","0.1.0":"2026-07-07T08:48:51.077Z","0.2.0":"2026-07-10T12:17:06.848Z","0.3.0":"2026-07-14T23:21:52.723Z"},"bugs":{"url":"https://github.com/astragenie/plugins-common/issues"},"license":"MIT","homepage":"https://github.com/astragenie/plugins-common#readme","repository":{"type":"git","url":"git+https://github.com/astragenie/plugins-common.git","directory":"packages/astramem-client"},"description":"Shared fail-silent client seam for the astramem memory plugin — provider resolution (dep-mode selector, dep-mode local/saas probe, runtime plugin-root discovery) plus wallclock-capped remember/recall calls — plus AstramemDaemonClient, a typed direct HTTP ","maintainers":[{"name":"heroboec","email":"shishkosv@gmail.com"}],"readme":"# @astragenie/astramem-client\n\nShared fail-silent client seam for the [astramem](https://github.com/astragenie/astramem-plugin)\nmemory plugin. Extracted from the two consumer implementations that grew\nindependently during FEAT-188:\n\n- dev-team `scripts/lib/memory/astramem-provider.ts` (S4) — dep-mode provider\n  loading with a hand-rolled local-then-saas health probe,\n- runner-plugin `src/scripts/lib/memory-transport.mts` (S1b) — dep-free runtime\n  discovery of the installed plugin.\n\nBoth strategies now live behind one resolution chain (see `src/resolve.ts`):\n\n1. injected provider (test seam),\n2. dep-mode `@astragenie/astramem-plugin/selector` → `resolveProvider()`,\n3. dep-mode `providers/local` + `providers/saas` factory probe (older plugin shas),\n4. runtime plugin-root discovery (`CLAUDE_PLUGIN_ROOT_MEMORY` env, or the\n   `astramem` CLI's PATH location → plugin root) with file-URL imports.\n\n## API\n\n```ts\nimport { rememberSilent, recallSilent, resolveWireProvider } from \"@astragenie/astramem-client\";\n\n// Fire-and-forget capture — true when accepted, false on ANY failure.\nconst ok = await rememberSilent({ id, type: \"lesson\", text, metadata });\n\n// Capped recall — response or null, never throws.\nconst res = await recallSilent({ query: \"worktree\", k: 5, agent: \"crew:builder\" });\n```\n\nContracts:\n\n- **Never throws.** Every failure — plugin absent, daemon down, wire drift —\n  resolves `false` / `null`.\n- **Wallclock-capped.** Resolution + call share one envelope\n  (`DEFAULT_CAP_MS` = 2000; override per call via `{ capMs }`).\n- **Cached.** First successful resolution is cached for the process lifetime.\n- **Test seams.** `_setWireProvider(fake | null)` and `_resetResolveCache()`.\n- **No CLI shelling.** The `astramem` binary is only used to *locate* the\n  installed plugin root — capture/recall never spawn it (dev-team#172).\n\n`@astragenie/astramem-plugin` is an **optional** peer: consumers that carry it\nget dep-mode resolution; consumers without it (e.g. CI) degrade cleanly.\n\nKeep this package import-cheap — it sits on hot ceremony paths in consumers\n(see runner-plugin#360 for what a cold multi-second import does there).\n\n## AstramemDaemonClient — direct daemon HTTP client\n\nA second, unrelated export: a typed client that talks to the astramem-local\ndaemon's REST surface directly, given an explicit `baseUrl` + `bearer` (no\nprovider resolution, no fail-silent swallowing — every failure throws a typed\n`DaemonError`). Use this when the caller already knows which daemon to talk to\n(e.g. a plugin provider implementation) rather than needing the\nresolve/probe chain above.\n\nHand-written from `astramemory-local`'s route handlers\n(`src/server/routes/*.ts`) — **not** imported from that repo, so this package\nhas no build-time dependency on the daemon. Follow-up: adopt\n`@astragenie/astramem-contracts` once it ships published types for these\nshapes; until then, drift surfaces as a rejected call, not a silent mismatch.\n\n```ts\nimport { AstramemDaemonClient, DaemonError } from \"@astragenie/astramem-client\";\n\nconst client = new AstramemDaemonClient({\n  baseUrl: \"http://127.0.0.1:7777\",\n  bearer: process.env.MEMORY_BEARER,\n  timeoutMs: 5000, // optional, default 5000\n});\n\nconst health = await client.health();\n\n// Canonical v1.0 ingest envelope, with idempotency support.\nawait client.ingestTranscript(envelope, { idempotencyKey: \"sha256-of-body\" });\n\nconst { hits } = await client.recall({ query: \"worktree\", k: 5, filters: { agent: \"crew:builder\" } });\nconst { hits: searchHits } = await client.search({ q: \"worktree\", repo: \"plugins-common\", limit: 10 });\nconst { id } = await client.remember({ text: \"prefer bun over npm here\", type: \"preference\" });\n\n// Lifecycle\nawait client.invalidate(id, \"superseded by newer note\");\nawait client.supersede(oldId, newId);\nawait client.promote(id, \"team\");\nawait client.restore(id);\nawait client.markUsed(id);\nconst { history } = await client.history(id);\nawait client.erase(id, \"user requested erasure\");\n\n// Provenance\nconst digest = await client.sessionDigest(sessionId);\nconst receipt = await client.whyMemory(id);\n\n// Consolidation\nconst summary = await client.runConsolidation({ merge_threshold: 0.92 });\nconst { proposals } = await client.listConsolidationProposals(\"pending\");\nawait client.acceptProposal(proposals[0].id);\nawait client.rejectProposal(proposals[1].id);\n\ntry {\n  await client.recall({ query: \"\" });\n} catch (err) {\n  if (err instanceof DaemonError && err.isDeterministic) {\n    // 4xx — the request itself was rejected; retrying unchanged won't help.\n  }\n}\n```\n\nError model (mirrors `astramem-plugin`'s `src/providers/local.ts` bands):\n\n- **4xx** → `DaemonError` with `band: \"deterministic\"` (`isDeterministic`) — do not retry.\n- **5xx / network / timeout** → `DaemonError` with `band: \"transient\"` (`isTransient\"`) — safe to retry.\n- **No retries by default.** `ingestTranscript` retries once on a transient\n  failure when the client is constructed with `retryIngestOnTransient: true`.\n  No other method retries.\n\nEvery exported type from `daemon-types.ts` that would otherwise collide with\nthe structural `WireProvider` mirrors above (`HealthResponse`,\n`RecallRequest`, `RecallHit`, `RecallResponse`) is re-exported under a\n`Daemon`-prefixed alias (`DaemonHealthResponse`, `DaemonRecallRequest`, ...)\n— the two type families describe different things (a minimal fail-silent\nsurface vs. the daemon's actual wire shapes) and are not interchangeable.\n","readmeFilename":"README.md"}