mem_session_start

Register the start of a new coding session

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 identifier

Should 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 name

The name of the project being worked on. Used for filtering and grouping memories.

Examples: engram, my-api, frontend-app

directory · string

Working directory path

The 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

Related Tools

• mem_session_end - Mark session as completed
• mem_session_summary - Save end-of-session summary
• mem_save - Save observations during the session
• mem_save_prompt - Record user prompts
• mem_context - Retrieve recent session context