Session Workflow

Every agent interaction with Synapses follows a lifecycle: initialize, work, end. This guide walks through each phase and shows how to get the most out of sessions.

The Session Lifecycle

session_init → [work: get_context, search, etc.] → end_session

1. Initialize the Session

session_init is always the first call. It bootstraps everything the agent needs in a single round-trip.

{
  "tool": "session_init",
  "arguments": {
    "agent_id": "claude-code-abc123"
  }
}

The response includes:

• Project identity — name, language, framework, repo scale (micro/small/medium/large)
• Scale guidance — recommended tool usage based on project size
• Working state — recent git commits, modified files, current branch
• Pending tasks — any unfinished tasks from previous sessions
• Active rules — architectural constraints in effect

The agent_id parameter is optional but recommended. It enables incremental mode.

2. Work Phase

During the work phase, the agent calls whatever tools it needs: get_context, search, get_context(mode="intent"), memory(action="save"), and so on. There are no restrictions on order or frequency.

// Find relevant code
{ "tool": "get_context", "arguments": { "query": "user authentication middleware" } }

// Search for specific patterns
{ "tool": "search", "arguments": { "query": "validateToken", "kind": "function" } }

// Remember a decision
{ "tool": "memory",
  "action": "save", "arguments": {
  "episode_type": "decision",
  "content": "Using JWT for auth instead of session cookies",
  "tags": ["auth", "architecture"]
}}

3. End the Session

end_session persists session state and cleans up resources.

{
  "tool": "end_session",
  "arguments": {
    "agent_id": "claude-code-abc123",
    "summary": "Implemented JWT auth middleware with token refresh"
  }
}

The summary is stored and surfaces in the next session_init call, giving future sessions continuity.

Incremental Mode

When you provide an agent_id, Synapses tracks what data has already been sent to that agent. On subsequent session_init calls within the same logical session, unchanged data is omitted.

// First call — full payload
{ "tool": "session_init", "arguments": { "agent_id": "agent-42" } }
// Returns: project identity, all rules, all pending tasks, working state

// Later call — only changes
{ "tool": "session_init", "arguments": { "agent_id": "agent-42" } }
// Returns: only new/changed tasks, new commits, updated rules

This is particularly useful for long-running agents or multi-turn conversations where re-sending the full project context would waste tokens.

Saving Mid-Session State

For long tasks, use tasks(action="save_state") to checkpoint progress without ending the session:

{
  "tool": "tasks",
  "arguments": {
    "action": "save_state",
    "agent_id": "agent-42",
    "state": {
      "current_task": "refactor-auth",
      "files_modified": ["internal/auth/jwt.go", "internal/auth/middleware.go"],
      "next_step": "Write tests for token refresh logic"
    }
  }
}

If the agent crashes or the session is interrupted, the next session_init with the same agent_id restores this state.

Typical Session Flow

Here is a complete example of an agent session for fixing a bug:

1. session_init(agent_id="fix-123")
   → Learn project is Go, large scale, has 2 pending tasks

2. get_context(query="handleWebhook timeout", intent="debug")
   → Get the function, its callers, error handling paths

3. search(query="context.WithTimeout", kind="call")
   → Find all timeout configurations

4. memory(action="save", episode_type="failure", content="Webhook handler uses 5s timeout but downstream API averages 3s", tags=["webhook","timeout"])
   → Record the finding

5. [Agent edits code to increase timeout and add retry logic]

6. tasks(action="update", task_id="fix-123", status="done", outcome="Increased webhook timeout to 10s, added retry with backoff")

7. end_session(agent_id="fix-123", summary="Fixed webhook timeout issue")

Best Practices

• Always call session_init first. It replaces the old 3-call startup pattern (get_project_identity + get_working_state + tasks(action="pending")).
• Use a consistent agent_id for related work across turns to benefit from incremental mode.
• Call end_session when you are done. It ensures tasks and memory are persisted cleanly.
• Save state for long tasks. If a task spans many tool calls, checkpoint with tasks(action="save_state") so progress is not lost on interruption.