@mono-agent/memory-supermemory 0.13.0 → 0.14.0

package/README.md

@@ -1,41 +1,76 @@
 # @mono-agent/memory-supermemory
 
+Use a local or hosted Supermemory service behind mono-agent's standard memory
+contract while keeping external-backend installation explicitly opt-in.
+
 ## Category
 
+<!-- package-metadata:start -->
+<!-- Generated by scripts/generate-package-docs.mjs. Do not edit by hand. -->
+
 Category: `context`
+Tier: `plugin`
+Catalog responsibility: Provides a MemoryStore over an external Supermemory instance (local OSS binary or hosted cloud) via its REST API: server-side extraction, hybrid recall, awaited completed-turn admission, and legacy best-effort writes.
+
+<!-- package-metadata:end -->
 
 Plugin tier: this package is released in the mono-agent lockstep, but is not
 installed with `@mono-agent/agent-app`; the operator installs and selects it explicitly.
 
 ## Responsibility
 
-Provides a `MemoryStore` (from `@mono-agent/agent-contracts`) backed by an external
-[Supermemory](https://supermemory.ai) instance — a local OSS binary
-(`supermemory-server`, MIT) or the hosted cloud — reached over its REST API. Selected via
-`config.memory.backend: "supermemory"`; the built-in BuJo engine remains the default.
-Supermemory extracts and consolidates memories **server-side**, so this backend needs no
-embeddings model and no memory chat LLM — the adapter just posts turns and searches.
+Provides a `MemoryStore` backed by an external
+[Supermemory](https://supermemory.ai) REST service: server-side extraction,
+hybrid recall, awaited run-keyed completed-turn admission, and legacy
+best-effort writes. The service may be a local OSS instance or hosted cloud.
 
 ## Install / Usage
 
 ```bash
-npm install @mono-agent/memory-supermemory@<matching-mono-agent-version>
+npm install @mono-agent/agent-app@latest @mono-agent/memory-supermemory@latest
 ```
 
-The package also ships `skills/mono-agent-supermemory/SKILL.md`, which guides a
-local configuration agent through service selection, privacy disclosure,
-validation, and a real recall smoke test. Installing the package never enables
-the backend by itself; `memory.backend: "supermemory"` remains the explicit opt-in.
-There is deliberately no separate plugin-preset loader: an installed plugin is
-offered by the normal wizard, while the skill owns later configuration changes.
+The lockstep `latest` tags resolve to the same framework version. If the host
+pins an older release, replace both `latest` tags with that same version.
+
+Installing the package does not enable it. Select the backend explicitly in the
+agent configuration; `writeMode: "capture"` sends the completed turn for
+server-side extraction:
+
+```json
+{
+  "memory": {
+    "backend": "supermemory",
+    "writeMode": "capture",
+    "supermemory": {
+      "baseUrl": "http://127.0.0.1:6767",
+      "container": "my-agent"
+    },
+    "recallTool": { "enabled": true }
+  }
+}
+```
+
+For hosted Supermemory, keep the secret outside JSON:
+
+```bash
+MONO_AGENT_MEMORY_SUPERMEMORY_API_KEY=replace-with-your-secret
+```
+
+The app configuration also accepts `apiKeyEnv`, `timeoutMs`, and
+`exposeMcpServer`. Those are host-level settings: the direct factory below
+accepts the already-resolved `apiKey` and does not read environment variables.
+
+Direct embedders can construct the store without `@mono-agent/agent-app`:
+
+<!-- doc-test:typescript -->
 
 ```ts
 import { createSupermemoryStore } from "@mono-agent/memory-supermemory";
 
 const store = createSupermemoryStore({
-  baseUrl: "http://127.0.0.1:6767", // local binary; or https://api.supermemory.ai for cloud
-  apiKey: process.env.SUPERMEMORY_API_KEY, // optional; omit for a keyless local instance
-  container: "my-agent",            // namespace tag scoping every add + search
+  baseUrl: "http://127.0.0.1:6767",
+  container: "my-agent",
   maxBytes: 64_000,
 });
 
@@ -46,38 +81,79 @@ await store.persistCompletedTurn({
   captureText: "User: Use dark mode.\nAssistant: Done.",
 });
 const block = await store.load("conv-1", "preferences");
+console.log(block?.content);
+await store.close();
 ```
 
-- `load(query)` → `POST /v4/search` (cached `/v3` fallback), formats ranked hits into a
-  markdown block capped at `maxBytes`. Degrades to `undefined` on any error.
-- `persistCompletedTurn` → one awaited `POST /v3/documents` containing the deterministic
-  summary and optional full capture text. A SHA-256-derived custom id keyed only by `runId`
-  keeps remote retries on one logical upsert. The store retains a bounded LRU of the 10,000 most
-  recently completed or exactly retried run fingerprints by default. Direct constructor users can
-  tune `SupermemoryStoreOptions.completedTurnCacheMaxEntries` up to a hard limit of 1,000,000; the
-  standard factory and agent JSON/env config deliberately use the bounded default. An exact
-  retained retry returns as a duplicate without another request and refreshes its LRU position;
-  conflicting reuse of a retained run id fails before a request. Inserting past the bound evicts
-  the least-recently-used successful completion. Failed and still-in-flight admissions do not
-  consume that completed-entry budget, and concurrent exact retries remain coalesced separately.
-  The cache retains at most two SHA-256 digests per entry—never raw run ids, conversation ids, or
-  turn content. A retry after eviction or process restart repeats the same stable-id upsert, so it
-  still converges remotely on one logical document, but the remote API does not expose enough
-  conditional/read state for mono-agent to classify that request as a duplicate or detect an old
-  conflicting payload. A different post-eviction payload can therefore replace the remote document
-  at that stable id; once its request starts, it becomes the new in-flight/local fingerprint and
-  concurrent alternatives fail as conflicts. Success returns the stable custom id after remote
-  admission, while any failure emits a constant content-free warning and is thrown so the harness
-  can report degradation. Raw run and
-  conversation ids are not placed in remote metadata. Documents over 1,000,000 bytes are
-  rejected rather than partially captured.
-- Legacy `appendHostSummary` / `scheduleCapture` remain compatible best-effort writes (one-liner /
-  full turn, async server-side extraction) and never throw. The harness does not call them when
-  the strong method is present.
-- `recall(query)` → hits shaped for the in-app `MemoryRecall` MCP tool.
+The package also ships `skills/mono-agent-supermemory/SKILL.md`, which guides a
+local configuration agent through service selection, privacy disclosure,
+validation, and a real recall smoke test. There is no separate preset loader;
+the normal wizard offers the plugin after installation.
+
+## Architecture
+
+### Data flow
+
+1. A completed turn enters `persistCompletedTurn()`, which awaits a
+   `POST /v3/documents` request and the service's admission response.
+2. A recall query enters `load()` or `recall()`, which requests
+   `POST /v4/search` and caches a `/v3/search` fallback after a 404 response.
+3. The store normalizes the ranked service hits and returns a bounded memory
+   block or the tool-oriented recall-hit shape.
+
+These steps describe network requests, not an in-process database. With hosted
+Supermemory, completed-turn text, legacy write text, recall queries, and returned
+memory leave the machine. Strong completed-turn metadata omits raw run and
+conversation ids, but its document content still contains the host-approved
+summary and optional capture text. A local service keeps the REST hop on-machine;
+service storage, extraction, access control, retention, and deletion remain
+Supermemory responsibilities in either deployment.
+
+### Package structure
+
+| Source file | Responsibility |
+| --- | --- |
+| `src/index.ts` | Validated convenience factory and public exports. |
+| `src/client.ts` | Raw Fetch-based `/v3/documents`, `/v4/search`, and cached `/v3/search` fallback client. |
+| `src/store.ts` | `MemoryStore` behavior, strong admission, legacy write compatibility, recall shaping, and queue draining. |
+| `src/format.ts` | UTF-8-bounded Markdown `MemoryBlock` rendering. |
+
+### Read and write behavior
+
+- `load(conversationId, query?)` searches with `query` when non-empty and falls
+  back to `conversationId` otherwise. It formats ranked hits into a Markdown
+  block capped at `maxBytes` and degrades to `undefined` on any client error.
+- `persistCompletedTurn(turn)` awaits one `/v3/documents` upsert containing the
+  deterministic summary and optional capture text. Its SHA-256-derived custom id
+  is keyed only by `runId`; failures are logged and rethrown so the harness can
+  report memory degradation without replacing the provider answer.
+- The strong path retains a default 10,000-entry bounded LRU of successful
+  run/payload fingerprints. Same-process exact retries return `duplicate` without
+  another request; retained conflicts fail before a request. After eviction or
+  restart, the stable remote id still converges on one logical upsert, but the API
+  cannot classify an old duplicate or reject an old conflicting payload.
+- Strong completed-turn documents above 1,000,000 bytes are rejected instead of
+  being partially admitted.
+- Legacy `appendHostSummary(conversationId, summary)` and
+  `scheduleCapture(conversationId, text)` remain best-effort compatibility paths.
+  Summary failure returns `bytesWritten: 0`; scheduled capture is serialized and
+  fire-and-forget. Neither throws to its caller, and the bundled harness does not
+  choose them while `persistCompletedTurn` is present.
+- `recall(query, { topK? })` propagates search errors and returns hits shaped for
+  the app-owned `MemoryRecall` tool.
 
 ## Public API
 
+### Start here
+
+| API | Use it for |
+| --- | --- |
+| `createSupermemoryStore` | Validate service settings and construct the normal HTTP-backed store. |
+| `validateSupermemoryConfig` | Validate direct-factory configuration without sending a network request. |
+| `SupermemoryMemoryStore` | Inject a fake/custom `SupermemoryClient` or tune the direct-constructor completion LRU. |
+| `createSupermemoryHttpClient` | Use the narrow REST client without the `MemoryStore` adapter. |
+| `formatHitsAsBlock` | Render normalized hits into a byte-bounded Markdown memory block. |
+
 <!-- public-api-inventory:start -->
 <!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
 
@@ -122,6 +198,13 @@ It does not own backend selection (that is `config.memory.backend`) or the
 the Supermemory service itself (extraction, consolidation, and storage all happen
 server-side). It does not run BuJo scheduled consolidation and ignores `mode`/`embeddings`/`llm`.
 
+## Related Documentation
+
+- [Built-in versus Supermemory backends](https://mono-agent-docs.vercel.app/memory/backends-comparison/)
+- [Write modes, durable capture, and recall](https://mono-agent-docs.vercel.app/memory/capture-and-recall/)
+- [Memory validation and CLI maintenance](https://mono-agent-docs.vercel.app/memory/validation-and-cli/)
+- [Memory configuration environment variables](https://mono-agent-docs.vercel.app/config/env-vars/#memory)
+
 ## Verification
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mono-agent/memory-supermemory",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Supermemory external memory backend: a MemoryStore over Supermemory's REST API (local OSS binary or hosted cloud).",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -29,7 +29,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mono-agent/agent-contracts": "0.13.0"
+    "@mono-agent/agent-contracts": "0.14.0"
   },
   "publishConfig": {
     "access": "public"