Managed memory and knowledge

Cloud Superbrain lets a hosted app remember useful context between calls. It can save facts and decisions, find them by words or meaning, answer from them with citations, and keep earlier versions when something changes.

It does not need a desktop session or an Obsidian vault. Each HivemindOS account receives an isolated memory store.

Use cloud-superbrain when your hosted product needs durable memory. Use the local Hive Superbrain when the user’s Obsidian vault should remain the editable source of truth.

Choose a recall mode

Semantic Recall and Memory Answer require a paid Cloud Superbrain plan. Lexical search, storage within the account’s plan, history, graph reads, capsules, and health checks do not consume agent credits. Read catalog.get before onboarding an account so your product can show its current plan, storage limits, and availability.

Semantic indexing runs when memory changes, so there is no idle compute charge to keep a model running. A newly written memory is immediately available to lexical search and becomes eligible for Semantic Recall after its index status is ready. Use memory.health when a workflow must confirm that state.

Operational memories such as action and handoff receipts stay out of default recall so routine execution history does not crowd durable facts, preferences, and decisions. Request a specific operational memoryType or set includeOperational: true when that history is the subject of the lookup.

Create typed memory

Only title and contentText are needed for a basic Markdown memory. Add a stable memoryKey when later calls should update one canonical subject instead of creating unrelated records.

const saved = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.create",
  {
    title: "Aurora compute funding decision",
    contentText: "Compute capacity starts only after the customer-funded job is accepted.",
    memoryKey: "decision:aurora-compute-funding",
    memoryType: "decision",
    project: "Aurora",
    confidence: 0.96,
    tags: ["compute", "commercial"],
    entities: ["Project Aurora", "Hive Compute"],
    evidenceCount: 3,
  },
  { idempotencyKey: "aurora-compute-decision-v1" },
);

if (!saved.ok) throw new Error(saved.error);
const memoryId = saved.result.memory.id;

Supported memory types are instruction, fact, decision, goal, commitment, preference, relationship, context, event, learning, observation, artifact, error, action, and knowledge. Optional fields include path, kind, mimeType, mediaUrl, links, metaTags, aliases, sourceType, actorRole, memoryOrigin, and cognitiveStage.

Cloud Superbrain rejects content that appears to contain a credential, private key, bearer token, seed phrase, or mnemonic. Store only the credential name and safe set/missing status; keep the value in a secret manager.

Use memory.batch for up to 25 already-bounded records. Each accepted record returns its own id and immutable generation receipt.

Search and answer

Lexical search is useful for autocomplete, retrieval before a model call, and predictable no-charge lookups:

const search = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.search",
  undefined,
  {
    query: {
      q: "customer-funded compute",
      project: "Aurora",
      memoryType: "decision",
      limit: 8,
    },
    idempotencyKey: "aurora-memory-search-001",
  },
);

Use semantic recall when wording may differ from the saved memory:

const recalled = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.recall",
  {
    query: "Who pays before an Aurora GPU starts?",
    mode: "hybrid",
    project: "Aurora",
    limit: 8,
  },
  { idempotencyKey: "aurora-memory-recall-001" },
);

Use Memory Answer when the caller wants a finished, grounded response:

const answered = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.answer",
  {
    query: "What is the Aurora compute funding policy?",
    limit: 8,
  },
  { idempotencyKey: "aurora-memory-answer-001" },
);

console.log(answered.result.answer);
console.log(answered.result.citedMemoryIds);

If no relevant managed memory can support an answer, the request returns a not-found response and releases the credit reservation. You are not charged. For a question of four or more words, a memory counts as support when it matches at least two of the question’s words, the exact phrase, or its meaning; one shared word is not enough.

Every hit includes its memory fields, excerpt, total score, matched signals, and score details. The excerpt is the part of the memory that holds the most words of the question. Search matches word forms, so weddings finds wedding, and a word that few of the account’s memories contain counts for more than one most of them share. Set trackUsage: false when a diagnostic lookup should not influence the soft usage signal. memory.usage can explicitly record retrieved or final-answer use for known memory ids.

Choose who reads the answer

Memory Answer has a default reader, and you can name another. memory.models lists every model that can read an answer, with its privacy tier, the reasoning settings it takes, its per-token price, and the most one answer with it can cost. The default is marked default: true. It needs no key.

const readers = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.models",
  {},
  { idempotencyKey: "memory-readers-001" },
);

Pass a reader’s id as model, and reasoningEffort (none, low, medium or high) when that reader lists it:

const answered = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.answer",
  {
    query: "What is the Aurora compute funding policy?",
    model: "@cf/openai/gpt-oss-120b",
    reasoningEffort: "medium",
  },
  { idempotencyKey: "aurora-memory-answer-002" },
);

console.log(answered.result.reader);

A setting a reader does not take is refused before anything is charged, never quietly changed. The response’s reader names the model that answered.

Price. With the default reader, an answer costs 5 credits. Another reader adds what it costs above the default for the same question, at HivemindOS rates, rounded up to a whole credit. A reader that costs less than the default still costs 5 credits. When the answer starts, the account is reserved the reader’s maximumCredits; it is then charged for the question that was actually sent, and the rest is released.

Private and confidential answers. Pass private: true, or call through the private base URL, to have the answer read only by a model that keeps nothing it is sent. Under the confidential base, name a reader that runs in an attested enclave as model: the default reader is private but not attested, so there is no default there. Either way the answer never uses Turbo ordering, and passing turbo: true with it is refused. memory.models under a tier’s base, or with privacy in its query, lists the readers that qualify.

Each memory keeps the strictest tier it was written in, and an answer reads it only with a reader that meets that tier. A memory written under the confidential base is never sent to an embedding model, so recall finds it by keyword. See private and confidential access.

Past conversations

Save a chat transcript as a memory and recall reads it by exchange: a user message and the replies that follow it. A memory is read as a transcript when its turns are marked **User:** and **Assistant:** (or an agent’s name), as conversation notes synced from the desktop brain are, or when its lines start with User: and Assistant:. Give the conversation’s date as startedAt or date in the memory’s frontmatter; without one, the date the memory was saved is used.

await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.create",
  {
    title: "Support chat with Dana",
    path: "Conversations/2026-09-14-dana.md",
    contentText: [
      "---",
      "startedAt: 2026-09-14T15:02:00Z",
      "---",
      "User: The replacement blender arrived cracked, same as the first one.",
      "Assistant: Sorry about that. I've refunded the second order to the original card.",
    ].join("\n"),
  },
  { idempotencyKey: "support-chat-dana-0914" },
);

When a search or recall returns a transcript among its hits, the response also carries conversationEvidence: the exchanges across the account’s transcripts that best match the question, laid out oldest first under each conversation’s date. conversationEvidenceMemoryIds names the memories they came from. A question about one detail of a long conversation gets the exchange that states it, not the transcript’s opening lines.

Memory Answer reads the same exchanges, together with the best-matching part of every other supporting memory, and is told today’s date, so questions like “how long ago” and “which came first” can be answered. When the conversations it found fit in the answer’s context whole, it reads every exchange of them in full, oldest first. When they are longer, the Turbo decision model first orders the exchanges by how likely each one is to hold the answer, and the answer reads short excerpts of the best 12,000 characters. The decision model is not a private model, so it orders exchanges only when every one of them was written in the standard tier, and a private answer never uses it. Pass turbo: false to keep keyword order; the response’s evidenceOrder says which order was used (keyword when the conversations were read whole). Neither choice changes the price.

memory.search responses carry a Server-Timing: memory;dur=<ms> header: the time the search itself took, apart from the network between you and the service.

Ask for only as much as you need

Recall returns whole memories by default, so a caller that only wants to know which memories are relevant still receives every body it will not read. Pass detail to choose how much of each hit comes back.

const survey = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.recall",
  { query: "Who pays before an Aurora GPU starts?", mode: "hybrid", detail: "abstract", limit: 8 },
  { idempotencyKey: "aurora-memory-survey-001" },
);

detail narrows the response only. It never changes which memories rank, their order, the grounding behind memory.answer, or what a recall costs — a narrowed recall is charged exactly like a full one. The response echoes the detail it applied.

Evolve instead of contradicting

When reviewed information replaces an active memory, use memory.evolve. The old record becomes superseded, the new record becomes the active canonical head, and both remain linked in the evolution chain.

const evolved = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.evolve",
  {
    contentText: "Aurora capacity starts only after the customer's maximum charge is reserved.",
    evolutionReason: "Clarified when funding is secured.",
  },
  {
    pathParameters: { memoryId },
    idempotencyKey: "aurora-compute-decision-v2",
  },
);

memory.update changes the current record in place. Use it for metadata or wording fixes that do not replace the underlying truth. memory.delete permanently removes a non-starter memory and requires an exact SuperAgent approval. An operation-only deletion key therefore needs services.invoke.cloud-superbrain.memory.delete, approvals.create, and approvals.decide in allowedOperations; include apiKeys.revoke only when the worker must also revoke its own key. Prefer archived or evolution when history still matters.

const report = await hive.services.invokeOperation(
  "cloud-superbrain",
  "memory.consolidate",
  { applyArchives: false },
  { idempotencyKey: "aurora-consolidate-001" },
);

for (const group of report.result.duplicateGroups) {
  console.log(group.canonicalTitle, group.memberIds, group.evolveHint);
}

Next: create narrow API keys, set per-operation limits, or use the local Hive Superbrain.