Get orkai

Sessions

Your agent's memory across conversations — what was done, what's pending, and key decisions, recalled at every session start.

Sessions are the backbone of orkai's persistent memory. Every time you finish working with your AI assistant, it saves a session summary — what was accomplished, what is pending, key decisions made, and which files were modified. The next time you start a session, your agent reads the latest session and picks up exactly where you left off.

No more re-explaining what you did yesterday. No more lost context between chats. Sessions are the reason orkai is called "the place your AI comes back to."

What is a session?

A session is a work session summary — a structured record of a single working session with your AI assistant. Each session stores:

  • What was accomplished — features shipped, bugs fixed, docs written
  • What is pending — unfinished work, blockers, follow-ups
  • Key decisions — architecture choices, trade-offs, rationale
  • Files modified — which source files changed and why

Sessions are category-scoped, so each project has its own session history. Long session text is auto-distributed into searchable sections and chunks, making it easy to find past decisions with session(action: "search", query: ...).

Session startup — what the agent does

At the start of every session, your agent follows a standard protocol:

  1. Calls overview() — surfaces recent sessions, standards, skills, and preferences.
  2. Reads User Preferences and Agent Preferences verbatim.
  3. Loads the latest session with session(action: "latest").
  4. Checks open plans / milestones / tasks in orkai for current work status.
  5. Briefs you on what it found — previous session, current milestone, relevant context.

This happens automatically. You do not need to tell the agent to check what happened last time — it is built into the session protocol.

Save a session

At the end of a working session, your agent offers to save a summary. The session is created through the MCP session tool: 

session(action: "create",
  name: "Session: auth refactor - 2026-06-25",
  description: "Refactored authentication middleware, added session token rotation",
  text: "## What was accomplished\n- Extracted auth middleware...\n## What's pending\n- Token refresh endpoint...\n## Key decisions\n- JWT over session cookies...\n## Files modified\n- internal/auth/middleware.go\n- internal/auth/token.go",
  category_ids: ["4c5996d0b1dac020d931388e834d5fc8"])

The name should include the topic and date. description is a one-line summary shown in lists. text is the full session body — long text is auto-distributed into sections and chunks for search.

Pick up where you left off

The latest action returns the most recent session for a project: 

session(action: "latest")
session(action: "latest", category: "orkai")
session(action: "latest", category_ids: ["4c5996d0b1dac020d931388e834d5fc8"])

This is the primary mechanism for context continuity. The agent calls it at startup, reads the pending items and decisions, and continues from where the last session ended. You can also call it manually to review what happened last time.

Sessions are semantically searchable. Find past decisions, discussions, and work by meaning rather than date: 

session(action: "search", query: "authentication middleware")
session(action: "search", query: "RLS filtering bug")
session(action: "search", query: "embedding provider migration")

Because session text is auto-distributed into sections and chunks, search returns the precise section that matches your query — not the entire session. Use session(action: "get", id: "...") to read the full session.

Browse session history

List all sessions in a project, paginated: 

session(action: "list")
session(action: "list", category: "orkai", limit: 10)
session(action: "list", category: "orkai", offset: 10, limit: 10)

overview() also surfaces the most recent sessions automatically, so you rarely need to list manually — the agent already knows what is recent.

Update a session

Sessions can be updated after creation — useful for adding follow-up notes or correcting details: 

session(action: "update",
  id: "e6f0f83d-d158-4019-81ab-d97d4f60ba8e",
  text: "## What was accomplished\n...\n## Follow-up\n- Deployed to prod, monitoring for 24h")

Updates replace the full text. Use get first to read the current content, then append or modify as needed.

Session end protocol

When a working session ends, the agent follows a standard closeout:

  1. Asks: "Would you like me to save this session for future reference?"
  2. If yes, creates a session with what was accomplished, pending items, key decisions, and files modified.
  3. Updates plan/milestone/task status in orkai if work moved (tasks completed, milestones closed).
  4. Offers to re-index if source files changed, so the code index stays fresh.

This protocol ensures every session leaves a trail. The next session picks up that trail automatically — no manual handoff, no lost context.

Typical workflow

  1. Session start: agent calls overview() → reads preferences → loads latest session → briefs you.
  2. During the session: agent works on tasks, checks standards, searches code, updates plan/milestone/task status.
  3. Session end: agent offers to save a session summary → updates plan/task status in orkai → offers to re-index.
  4. Next session: agent reads the saved session and continues from the pending items.

See Plans, milestones & tasks for how the agent tracks structured work across sessions, and MCP for connecting your assistant.