@volter/twin-supermemory

Local Supermemory twin for the memory-API surface (api.supermemory.ai): document/memory ingestion (add / batch / list / get / update / delete / bulk-delete), container-tag scoping (per-project memory isolation), a REAL AND/OR/negate metadata filter evaluator (metadata / numeric / string_contains / array_contains condition types), a deterministic, clearly-labeled lexical search ranking with paragraph chunking, and org settings — built on the shared @volter/world-core kernel. Memories are the resource: every write is an action appended to the kernel log, every read uses the kernel’s tree.

bun packages/twin/supermemory/src/cli.ts

Coverage

This is a v1 slice of the Supermemory API, not the full surface. The manifest is grounded against the installed [email protected] SDK's own Stainless-generated types — the EXACT version the primary consumer (Ponder's apps/server/src/libs/supermemory/index.ts) resolves, and the version the SDK-parity test pins (the SDK's surface moved within v4: by 4.24.2 memories.add no longer exists) — plus a live unauthenticated probe of api.supermemory.ai that grounded the {error, details?} error envelope. Modeled done: the v3 document surface (add/batch/list/get/update/delete-by-id-or-customId/bulk-delete/processing, with the SDK-documented containerTag/customId/flat-metadata validation rules), POST /v3/search (lexical ranking, container scoping, chunking with isRelevant/context chunks, chunkThreshold, limit, docId, includeFullDocs, and the full filter grammar including Ponder's exact {AND:[{key,value,negate}]} shape), /v3/settings get/update, per-container isolation, readOnly-mode write rejection, and a pull connector over an injected client.

Left as todo (honest gaps, not yet modeled): multipart file upload, customId upsert semantics, vendor id-format/status-string/default-ordering parity items, the whole v4 memory-entry surface (DELETE|PATCH /v4/memories forget/versioned-update, POST /v4/search, POST /v4/profile — these are built on LLM extraction in the real product), the /v3/connections management surface, the ingestion status lifecycle (queued → extracting → chunking → embedding → indexing, so /v3/documents/processing is non-empty; the twin ingests synchronously today), auth 401 parity, exact error-string parity, connector settings-pull/push, and fixture seeding. Unmodeled routes fail vendor-shaped (404 {error, details}) — never a fabricated success.

How the twin answers where the vendor runs a model or the network. Search is deterministic LEXICAL ranking, clearly labeled (this repo's honest-design precedent, like anthropic's [twin-stub:…]): distinct-query-token overlap scored per paragraph chunk, document score = best chunk, ties broken by recency then id (src/supermemory-search.ts). It is REAL computed behavior — a search-ignoring or ranking-ignoring implementation fails the capability suite — but synonyms and paraphrases will not match, and score values are twin-defined in [0,1]. rerank:true and rewriteQuery:true are accepted and ranked with that same scorer over the literal query. LLM-derived title/summary are honestly null, never fabricated. Content is stored as plaintext (type:"text") and /v3/documents/file fails vendor-shaped. timing on search responses is a deterministic 0, not a fabricated latency.

See src/supermemory-capabilities.ts for the full manifest (the real vendor surface is the denominator — coverage is honest and partial until the twin reaches it).

No UI mirror

Supermemory does ship a consumer app, but per the contributor recipe's rule ("when someone does this vendor's core job, do they open a browser or write code?") the API is the product for the integrator this twin exists to serve: an integrator adds memory to their agent/app by code — the supermemory SDK against api.supermemory.ai — which is exactly how the primary consumer (Ponder's server) uses it, headlessly, per-project. The consumer app is the vendor's own end-user product built ON that API, not the surface an integrator works in (same reasoning as stream's "internal admin console" note). So this pack ships no mirror and no UI capabilities; coverage is API + connector.

SDK parity

src/supermemory-sdk.integration.test.ts drives this twin with the real, unmodified [email protected] npm SDK through the consumer's exact call shapes (memories.add with containerTag + typed metadata; search.execute with containerTags/includeFullDocs/AND filters and the consumer's exact result mapping), offline, via the SDK's own documented baseURL option — no fetch override, no monkey-patching. Negative paths surface as the SDK's real typed errors (Supermemory.NotFoundError, Supermemory.BadRequestError).