Memco

Class Session

An open session, with every session-bound memory operation applied.

Returned by MemoryOperations.startSession, MemoryOperations.withSession and MemoryOperations.resumeSession alike; not constructed directly. No method here takes a session id or a domain: this object supplies both. That is the point of it — a call that silently drops the session id is still a valid call. It opens a session of its own and records the search there, so the series you were assembling quietly splits in two, and a later rating lands against a search you did not mean to make.

A session opened with an externalId holds a key acting as that user, and Session.close ends it; so does leaving an await using block. Close it when you are done: the service caps how many live keys each user may hold. A session dropped without closing has its key ended eventually — once the session has been garbage-collected, by the next call the client makes — but closing ends it at once, and is the only way that says when.

Any other session holds nothing: the contract has no operation that ends a session, and a session id stays usable for as long as it is named, so closing one changes nothing and await using bounds the region of code a session belongs to, which is a claim about the reader's attention rather than about a resource.

Index
id instructions domain toolCatalog
[asyncDispose] close getSession search getMemory createMemory enrichMemory shareFeedback revertMemory importMemories tools
id: string

The session id that was opened.

instructions: Instructions

What the service said when the session was opened.

domain: DomainEntry | null

What the service said about the session's domain, or null when its listing did not describe it.

toolCatalog: readonly ToolDescriptor[] | null

What MemoryOperations.listTools reported when this session was opened, which tools filters against. null when that fetch failed -- every tool is then treated as available rather than none.

  • Close the session at the end of an await using block.

    Returns Promise<void>

    Once close has.

  • Close the session, ending the key it holds if it acts for one of your users.

    Only a session opened with an externalId holds anything: its key, which is revoked here rather than left live until it expires. Every later call through the session, its tools, or a memory it returned is then refused locally with MemcoConfigError. A call still in flight keeps the key until it finishes, and the key is ended then.

    Ending the key is best effort. If the service cannot end it, a warning naming the key's id — never its value — is logged and nothing is thrown: the client tries again before it next opens a session for that user, and when it closes, and the key expires on its own regardless. After the client is closed, this does nothing.

    A session opened without an externalId holds nothing, so closing it changes nothing and it stays usable. Safe to call more than once.

    Returns Promise<void>

    const session = await client.memory.startSession('coding', {
      externalId: 'customer-42'
    })
    await session.search('how does X work')
    await session.close()

  • Fetch one memory in full, by an idx this session 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, its feedback() bound to this session — unlike MemoryOperations.getMemory, which has no session of its own to bind.

  • This session's operations, described and rendered for an LLM.

    Each tool carries what the operation is for, a JSON Schema for its arguments, and a call that renders the result as text. Every one is bound to this session, so nothing a model sends can change which session a call is recorded under.

    The toolset hands itself to a framework — toLangChain(), toAnthropic(), toOpenAI() — or runs what a model named with call().

    An operation is included only when your token's role permits it, as reported by MemoryOperations.listTools when this session was opened. This only shapes what is offered here — it does not gate calling a Session method directly.

    Parameters

    • options: ToolsOptions = {}

      The prefix every tool name starts with, when a host calls the tools by other names than memco_<op>.

    Returns Toolset

    One tool per operation your role permits, as a Toolset.

    MemcoConfigError If no tool name can carry the prefix.

    await using session = await client.memory.withSession('coding')
    createAgent({ model, tools: await session.tools().toLangChain() })
    session.tools({ prefix: 'memco__' }).tools[0].name // 'memco__search'

On this page

PropertiesMethodsPropertiesReadonlyidReadonlyinstructionsReadonlydomainReadonlytoolCatalogMethods[asyncDispose]closeExamplegetSessionsearchgetMemorycreateMemoryenrichMemoryshareFeedbackrevertMemoryimportMemoriestoolsThrowsExample