Memco

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 resumeSession withSession search getSession 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 lists the domains, which is where Session.domain comes from, and 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.

    With an externalId, the session acts as that user of yours: opening it mints a key acting as them, lists the domains under that key, and only then starts the session, all under the key. Session.close ends it.

    Parameters

    • domain: string

      The domain to work in.

    • options: SessionOptions = {}

      The user to act as, if any, and a 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 or the externalId is blank, or keyTtlMinutes is not a whole number of minutes from 1 up. Each is refused before a key is minted.

    MemcoAPIError If the service refuses. With an externalId, a failure after the key was minted ends it before this is thrown.

    MemcoTimeoutError If the deadline passes first. With an externalId, the key is ended once its mint lands, without this waiting for it.

    const session = await client.memory.startSession('coding', {
      externalId: 'customer-42'
    })
    try {
      await session.search('how do I rotate an API key')
    } finally {
      await session.close()
    }

  • Take up a session opened earlier, by its id, instead of starting another.

    Every call already takes a session id, and an id stays usable for as long as it is named, so a session can outlive the process that opened it: keep its id, and resume it where the work continues. Nothing calls StartSession, so the searches made here join the series the id began. Opening is otherwise the same as startSession: the domains are listed and the tool catalog fetched, and with an externalId a new key is minted first, for both. A resumed session carries no opening instructions; they were given when it started.

    The session is looked up with getSession, under the session's own credential, so an id that is unknown, or not this caller's, is refused here rather than at the first call. Its domain is the one it was started in, which the service reports and supplies on every call it makes, and which cannot be changed.

    Parameters

    • sessionId: string

      The id of the session to resume, as a session's id or a search result's sessionId reported it.

    • options: SessionOptions = {}

      The user to act as, if any, and a per-call deadline.

    Returns Promise<Session>

    The session, with every session-bound operation already applied.

    MemcoInvalidRequestError If the session id or the externalId is blank, or keyTtlMinutes is not a whole number of minutes from 1 up. Each is refused before a key is minted.

    MemcoNotFoundError If the session is unknown or not the caller's. With an externalId, the key is ended before this is thrown.

    MemcoAPIError If the service refuses. With an externalId, a failure after the key was minted ends it before this is thrown.

    MemcoTimeoutError If the deadline passes first.

    const session = await client.memory.resumeSession(stored.sessionId, {
      externalId: 'customer-42'
    })
    try {
      await session.search('what did we decide about retries')
    } finally {
      await session.close()
    }

  • 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, with an externalId, mints one key — and returns the same object, which is what makes it safe to hold in a variable. Leaving an await using block closes the session, which ends the key a session acting as one of your users holds.

    Parameters

    • domain: string

      The domain to work in.

    • options: SessionOptions = {}

      The user to act as, if any, and a 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', {
      externalId: 'customer-42'
    })
    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' }]
    })

  • Look a session up: the domain it runs in and what has happened under it.

    Answered only for a session the caller may continue — under an impersonation key, one that user started.

    Parameters

    • sessionId: string

      The session id, as a session's id or a search result's sessionId reported it.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<SessionInfo>

    The session's domain, start and counts. The counts are kept asynchronously, so they can trail a call made just before.

    MemcoInvalidRequestError If the session id is blank.

    MemcoNotFoundError If the session is unknown or not the caller's. The two are answered alike, so an id cannot be probed.

    const info = await client.memory.getSession(stored.sessionId)
    console.log(info.domain, info.searches)

  • 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.

On this page

MethodsMethodslistDomainsThrowsExamplelistToolsExamplestartSessionThrowsThrowsThrowsExampleresumeSessionThrowsThrowsThrowsThrowsExamplewithSessionExamplesearchThrowsExamplegetSessionThrowsThrowsExamplegetMemoryThrowsExamplecreateMemoryThrowsenrichMemoryThrowsshareFeedbackThrowsrevertMemoryExampleimportMemoriesThrows