Skip to Content

Class MemoryOperations

The memory operations, reached as client.memory.

The prose here is hand-written and addresses a developer. The service's own copy — what a model is told each of these operations does — is generated into src/gen/toolCopy.ts instead, because TypeScript keeps no doc comments at run time for agent.ts to read back off these methods.

Index
listDomains listTools startSession withSession search getMemory createMemory enrichMemory shareFeedback revertMemory importMemories

  • List the memory domains this credential may name.

    This is also how the client learns the limits the service enforces, so it runs once while the connection is being verified. Calling it again refreshes them.

    Parameters

    Returns Promise<DomainList>

    The domains, the service's guidance, and the limits it enforces.

    MemcoAuthenticationError If the credential is rejected.

    const { domains } = await client.memory.listDomains()
    console.log(domains.map(domain => domain.slug))

  • Every method this contract declares, and which of them your token's role permits.

    The catalog itself never varies; only availability does. Availability names a permission, not a guarantee: a method reported available may still be refused for a reason unrelated to role, such as a memory domain with no network provisioned for it.

    startSession calls this once per session and caches the result, which is what Session.tools filters against — so calling this directly is for a caller that wants the catalog itself, not for shaping what a session offers.

    Parameters

    Returns Promise<readonly ToolDescriptor[]>

    One descriptor per method the contract declares.

    const catalog = await client.memory.listTools()
    const names = catalog.filter(tool => tool.available).map(tool => tool.name)

  • Open a session, so the searches made under it are recorded as one series.

    Also fetches the tools your token's role currently permits, which is what Session.tools filters against for the life of the session. That fetch is best-effort: if it fails after the retries RETRYABLE_METHODS already gives it, a warning is logged and every tool is treated as available rather than none, so a transient failure degrades Session.tools to unfiltered rather than to empty.

    Parameters

    • domain: string

      The domain to work in.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<Session>

    The open session, with every session-bound operation already applied — withSession returns the same kind of object.

    MemcoInvalidRequestError If the domain is blank.

  • Open a session and bind it, so no later call can drop the handle.

    The same as startSession: kept as its own name for the context-manager call site, wherever the session outlives a line or two. Nothing is sent until the result is awaited, and awaiting it twice opens one session and returns the same object — which is what makes it safe to hold in a variable.

    Parameters

    • domain: string

      The domain to work in.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns SessionOpener

    An opener. Await it for the session, which is the disposable one.

    await using session = await client.memory.withSession('coding')
    const result = await session.search('how does health checking work')

  • Search for existing knowledge.

    Pass a domain or a session id — a search naming neither is refused before anything is sent, because the request has no way to name a domain.

    Parameters

    • query: string

      What you want to know, in plain language.

    • options: SearchOptions = {}

      The scope to search in, tags to narrow by, and a deadline.

    Returns Promise<SearchResult>

    What matched, and the session it was recorded against.

    MemcoInvalidRequestError If the query is blank, if neither a domain nor a session is named, or if the query exceeds the service's limit.

    const result = await client.memory.search('gRPC health checking', {
      domain: 'coding',
      tags: [{ type: 'language', value: 'typescript' }]
    })

  • Fetch one memory in full, by an idx a search returned.

    Parameters

    • idx: string

      The handle, copied exactly as it appeared in a search response.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<Memory>

    The memory.

    MemcoNotFoundError If nothing answers to that handle.

    const memory = await client.memory.getMemory('memory-6oiv6b-1')

  • Save new knowledge.

    The write is accepted asynchronously, so the result carries the operation id addressing it rather than the memory it will become.

    Parameters

    Returns Promise<WriteResult>

    The operation id, when the write can be undone, and guidance.

    MemcoInvalidRequestError If a required field is blank, if neither a domain nor a session is named, or if the title and content together exceed the service's combined limit.

  • Add to a memory a search returned, or open a new one.

    Parameters

    • options: EnrichMemoryOptions

      What to add, which memory to add it to, and a deadline. Pass 'new' as the memory idx to open a standalone memory instead.

    Returns Promise<WriteResult>

    The operation id, when the write can be undone, and guidance.

    MemcoInvalidRequestError If a required field is blank or the title and content together exceed the service's combined limit.

  • Rate the results of one search.

    Ratings are what move the reliability signal on an insight, so this is the half of a search that makes the next one better.

    Parameters

    Returns Promise<FeedbackResult>

    What was recorded, and anything the service wants to say back.

    MemcoInvalidRequestError If no ratings are given, if a rating names no idx, or if there are more than the service accepts.

  • Undo one of your own writes.

    Every outcome is a successful call: NOT_FOUND, EXPIRED and REFUSED report a caller-visible state rather than a service failure, so read RevertResult.outcome rather than relying on this to throw.

    Parameters

    • operationId: string

      The handle a write returned.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<RevertResult>

    What the revert actually removed.

    const reverted = await client.memory.revertMemory(created.operationId!)
    if (reverted.outcome === RevertOutcome.EXPIRED) {
      console.log('outside the revert window')
    }

  • Contribute many memories at once.

    A batch longer than the service accepts is split across several calls by the SDK, and every outcome is renumbered back into the array that was passed in — so ImportOutcome.index always indexes memories, whatever the service's batch limit happens to be.

    Each memory is judged on its own, so a refused entry does not stop the others. A batch mints no operation id, so an import cannot be reverted.

    Parameters

    • memories: Iterable<ImportedMemory>

      The memories to import. At least one, each with at least one query and one insight.

    • options: ImportMemoriesOptions = {}

      The scope to import into, and a deadline.

    Returns Promise<ImportResult>

    One outcome per memory, in the order they were given.

    MemcoInvalidRequestError If the batch is empty, if an entry is incomplete, or if neither a domain nor a session is named.

Quickstart