> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  This tool is part of the **agent** profile and uses deferred loading.
</Note>

## Parameters

<ParamField path="id" type="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.
</ParamField>

<ParamField path="project" type="string" required>
  Project name

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

  Examples: `engram`, `my-api`, `frontend-app`
</ParamField>

<ParamField path="directory" type="string">
  Working directory path

  The file system path where the session is running. Useful for context but not required.

  Example: `/home/user/projects/engram`
</ParamField>

## Response

<ResponseField name="result" type="string">
  Confirmation message with session ID and project
</ResponseField>

**Example:**

```
Session "session-2026-03-03-1430" started for project "engram"
```

## Usage Examples

### Basic Session Start

```json theme={null}
{
  "id": "session-2026-03-03-1430",
  "project": "engram"
}
```

**Response:**

```
Session "session-2026-03-03-1430" started for project "engram"
```

### With Working Directory

```json theme={null}
{
  "id": "opencode-abc123",
  "project": "my-api",
  "directory": "/home/user/projects/my-api"
}
```

**Response:**

```
Session "opencode-abc123" started for project "my-api"
```

## Session Lifecycle

```mermaid theme={null}
graph LR
    A[mem_session_start] --> B[Work: mem_save, mem_search, etc.]
    B --> C[mem_session_summary]
    C --> D[mem_session_end]
```

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

<Info>
  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.
</Info>

## 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

<Tip>
  **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
</Tip>

## Related Tools

* [`mem_session_end`](/mcp/mem-session-end) - Mark session as completed
* [`mem_session_summary`](/mcp/mem-session-summary) - Save end-of-session summary
* [`mem_save`](/mcp/mem-save) - Save observations during the session
* [`mem_save_prompt`](/mcp/mem-save-prompt) - Record user prompts
* [`mem_context`](/mcp/mem-context) - Retrieve recent session context