Skip to main content

​
Overview

Create a new session record to track the beginning of a coding session. Sessions group related observations and provide chronological context for memory retrieval.
This tool is part of the agent profile and uses deferred loading.

​
Parameters

​
id
string
required
Unique session identifierShould be unique across all sessions. Common patterns:
  • UUIDs: 550e8400-e29b-41d4-a716-446655440000
  • Timestamped: session-2026-03-03-1430
  • Agent-generated: opencode-abc123
This ID is used to associate observations with the session via mem_save, mem_save_prompt, etc.
​
project
string
required
Project nameThe name of the project being worked on. Used for filtering and grouping memories.Examples: engram, my-api, frontend-app
​
directory
string
Working directory pathThe file system path where the session is running. Useful for context but not required.Example: /home/user/projects/engram

​
Response

​
result
string
Confirmation message with session ID and project
Example: 
Session "session-2026-03-03-1430" started for project "engram"

​
Usage Examples

​
Basic Session Start

{
  "id": "session-2026-03-03-1430",
  "project": "engram"
}
Response: 
Session "session-2026-03-03-1430" started for project "engram"

​
With Working Directory

{
  "id": "opencode-abc123",
  "project": "my-api",
  "directory": "/home/user/projects/my-api"
}
Response: 
Session "opencode-abc123" started for project "my-api"

​
Session Lifecycle

  1. Start: Call mem_session_start at the beginning of a coding session
  2. Work: Use mem_save, mem_search, mem_context, etc. during the session
  3. Summarize: Call mem_session_summary when significant work is complete
  4. End: Call mem_session_end to mark the session complete

​
When to Use

  • Agent initialization: When an AI coding assistant starts working
  • Manual sessions: When using the CLI or API directly
  • Session tracking: To maintain chronological context across multiple interactions

​
Idempotency

This tool is idempotent — calling it multiple times with the same id won’t create duplicate sessions. If the session already exists, the call succeeds without error.

​
What Gets Created

A session record with:
  • id: The session identifier
  • project: Project name
  • directory: Working directory (if provided)
  • started_at: ISO 8601 timestamp of creation
  • ended_at: null until mem_session_end is called
  • summary: null until mem_session_end is called

​
Session ID Best Practices

Generate stable session IDs that can be used consistently throughout a coding session:
  • Use UUIDs for guaranteed uniqueness
  • Use timestamps if you only run one session at a time per project
  • Include the agent name for debugging: opencode-{uuid}
  • Store the session ID in agent state so all tool calls use the same ID

Build docs developers (and LLMs) love

Get started for freeTalk to us