Skip to content

sessions.md

Latest commit

 

History

History
99 lines (68 loc) · 2.71 KB

sessions.md

File metadata and controls

99 lines (68 loc) · 2.71 KB

Sessions

Sessions track conversation history and drive long-term memory extraction. When a session is committed, OpenViking analyzes the messages and the contexts that were used, then writes durable memories back into the knowledge base.

Typical flow

// 1. Start a session
const session = await huscarl.sessions.create();

// 2. Add messages as the conversation progresses
await huscarl.sessions.addMessage(session.sessionId, "user", "How do I configure retries?");

// 3. Search for relevant context
const results = await huscarl.retrieval.search("retry configuration", {
  sessionId: session.sessionId,
});

// 4. Add the assistant's reply
await huscarl.sessions.addMessage(session.sessionId, "assistant", "You can configure...");

// 5. Record which contexts were actually used
await huscarl.sessions.used(session.sessionId, {
  contexts: results.resources.map(r => r.uri),
});

// 6. Commit — archives messages and triggers memory extraction
await huscarl.sessions.commit(session.sessionId);

Methods

create(options?)

Creates a new conversation session.

const session = await huscarl.sessions.create();
const session = await huscarl.sessions.create({ sessionId: "my-session-id" });

list()

Returns all active sessions for the current user.

const sessions = await huscarl.sessions.list();

get(sessionId)

Returns details for a session, including its message count.

const details = await huscarl.sessions.get(session.sessionId);
console.log(details.messageCount);

addMessage(sessionId, role, content)

Appends a message to the session. Content can be a plain string or an array of typed parts.

// Simple string
await huscarl.sessions.addMessage(sessionId, "user", "What is the retry limit?");

// Structured parts (TextPart, ContextPart, ToolPart)
await huscarl.sessions.addMessage(sessionId, "assistant", [
  { type: "text", content: "The retry limit is 3." },
]);

used(sessionId, options)

Records which contexts and skills were actually used in the current turn. This informs memory extraction at commit time — only pass what was genuinely useful.

await huscarl.sessions.used(sessionId, {
  contexts: ["viking://resources/docs/config.md"],
  skill: "answer-question",
});

commit(sessionId)

Archives the session's messages and triggers long-term memory extraction. The session history is preserved but the active message window is cleared.

const result = await huscarl.sessions.commit(sessionId);
console.log(result.status, result.archived);

delete(sessionId)

Permanently deletes a session and all its messages.

await huscarl.sessions.delete(sessionId);