Sessions API

Track your work sessions and get memory context injected at session start. A session groups observations and provides the context window that drives memory extraction — start one at the beginning of a work session, end it when you're done, and the API enqueues a batch extraction job that turns your observations into structured memories.

See Session Lifecycle for a full explanation of how sessions drive memory extraction, or Coding Agent Memory cookbook for a worked integration.

Base URL and Authentication

https://api.neuroloom.dev

All endpoints require an API key:

Authorization: Token $MEMORIES_API_TOKEN

Session IDs

Session identifiers are externally supplied strings (e.g. sess-abc123). You choose and manage them — they must be globally unique across all workspaces. The MCP session_start tool auto-generates a sess- prefixed ID if you do not supply one.

Start a Session

POST /api/v1/sessions/start

Start a new session and register it with Neuroloom. Call this at the beginning of a work session. The response includes the session object for use in subsequent calls. A conflict on session_id returns 409 Conflict.

session_start(
  project_path="/Users/dev/projects/neuroloom"
)

import httpx, os

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/sessions/start",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    json={
        "session_id": "sess-abc123",
        "project_name": "neuroloom",
        "branch_name": "feature/graph-api",
        "user_id": "user_01xyz",
        "metadata": {
            "claude_version": "claude-sonnet-4-6",
            "env": "development",
        },
    },
)
session = response.json()
session_id = session["session_id"]

curl -X POST "https://api.neuroloom.dev/api/v1/sessions/start" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "project_name": "neuroloom",
    "branch_name": "feature/graph-api",
    "user_id": "user_01xyz",
    "metadata": {
      "claude_version": "claude-sonnet-4-6",
      "env": "development"
    }
  }'

Request body

Response — 201 Created, session object.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "sess-abc123",
  "workspace_id": "ws-xyz789",
  "project_name": "neuroloom",
  "branch_name": "feature/graph-api",
  "user_id": "user_01xyz",
  "user_email": null,
  "is_active": true,
  "started_at": "2026-03-20T09:00:00Z",
  "ended_at": null,
  "summary": null,
  "metadata_json": {
    "claude_version": "claude-sonnet-4-6",
    "env": "development"
  },
  "created_at": "2026-03-20T09:00:00Z",
  "updated_at": null
}

End a Session

POST /api/v1/sessions/{session_id}/end

Mark the session inactive and enqueue the generate_session_summary ARQ job. The job extracts structured memories from the session's observations asynchronously — the HTTP response is returned immediately and does not block on extraction.

session_end(
  session_id="sess-abc123",
  summary="Implemented graph API endpoints for D38. Added explore and path endpoints with BFS traversal."
)

import httpx, os

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/sessions/sess-abc123/end",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
)
session = response.json()
assert session["is_active"] is False

curl -X POST "https://api.neuroloom.dev/api/v1/sessions/sess-abc123/end" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Path parameters

Response — 200 OK, updated session object with is_active: false and ended_at set.

Get Session Context

GET /api/v1/sessions/{session_id}/context

Return the session record alongside recent high-importance memories and recent past session summaries. The response is formatted for direct injection into a Claude Code session start prompt.

session_get_context(
  session_id="sess-abc123",
  max_memories=15
)

import httpx, os

response = httpx.get(
    "https://api.neuroloom.dev/api/v1/sessions/sess-abc123/context",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    params={"max_memories": 15},
)
context = response.json()
# Inject context["context"]["recent_memories"] into your session prompt

curl "https://api.neuroloom.dev/api/v1/sessions/sess-abc123/context?max_memories=15" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Query parameters

Response — 200 OK

{
  "session": {
    "session_id": "sess-abc123",
    "project_name": "neuroloom",
    "branch_name": "feature/graph-api",
    "is_active": true,
    "started_at": "2026-03-20T09:00:00Z"
  },
  "context": {
    "recent_memories": [
      {
        "memory_id": "mem-a1b2c3d4e5f6g7h8",
        "title": "Prefer async SQLAlchemy for all DB calls",
        "memory_type": "pattern",
        "importance_score": 0.9,
        "narrative": "All database operations must use async/await..."
      }
    ],
    "recent_sessions": [
      {
        "session_id": "sess-prev001",
        "summary": "Refactored memory search to use hybrid scoring.",
        "ended_at": "2026-03-19T17:00:00Z"
      }
    ],
    "workspace_summary": "Active development on Neuroloom graph API. Primary patterns: async SQLAlchemy, pgvector cosine similarity."
  }
}

The context object is designed for direct injection into a session start prompt. Paste context.recent_memories and context.recent_sessions verbatim.

List Sessions

GET /api/v1/sessions/

Return sessions for the authenticated workspace ordered by started_at descending (most recent first). Returns a paginated envelope with a total count.

Query parameters

Response — 200 OK

{
  "count": 42,
  "results": [
    {
      "session_id": "sess-abc123",
      "project_name": "neuroloom",
      "branch_name": "feature/graph-api",
      "is_active": false,
      "started_at": "2026-03-20T09:00:00Z",
      "ended_at": "2026-03-20T17:00:00Z",
      "summary": "Implemented graph API for D38."
    }
  ]
}

count is the total number of sessions in the workspace, not just the current page. Use limit and offset to paginate.

curl "https://api.neuroloom.dev/api/v1/sessions/?limit=10&offset=0" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Get a Session

GET /api/v1/sessions/{session_id}

Fetch a single session by its external session identifier.

Response — 200 OK, session object.

Session response fields

curl "https://api.neuroloom.dev/api/v1/sessions/sess-abc123" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Update a Session

PATCH /api/v1/sessions/{session_id}

Update mutable session fields. Supply only the fields you want to change. session_id and workspace_id are immutable.

Request body — all fields optional

Response — 200 OK, updated session object.

curl -X PATCH "https://api.neuroloom.dev/api/v1/sessions/sess-abc123" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Implemented D38 graph API. Explore and path endpoints now live.",
    "metadata": {
      "claude_version": "claude-sonnet-4-6",
      "pr_url": "https://github.com/org/repo/pull/42"
    }
  }'

Error Responses

{ "detail": "Session 'sess-abc123' not found." }

Pagination

All list endpoints use limit + offset pagination. To fetch the second page of 10 results: ?limit=10&offset=10.

Related

• Memory Lifecycle — how sessions drive observation capture and memory extraction
• Workspace Isolation — how sessions scope to a workspace
• Coding Agent Memory — worked session integration example