Sessions represent coding work periods. Each session groups related observations.
Create Session
POST /sessions
Create a new session or update an existing one.
Request Body
Unique session identifier. Use UUIDs or timestamps for uniqueness.
Project name (e.g., “engram”, “my-app”)
Response
Example
curl -X POST http://127.0.0.1:7437/sessions \
-H "Content-Type: application/json" \
-d '{
"id": "session-abc123",
"project": "engram",
"directory": "/home/user/projects/engram"
}'
{
"id": "session-abc123",
"status": "created"
}
End Session
POST /sessions/{id}/end
Mark a session as completed with an optional summary.
Path Parameters
Request Body
Optional session summary describing what was accomplished
Response
Example
curl -X POST http://127.0.0.1:7437/sessions/session-abc123/end \
-H "Content-Type: application/json" \
-d '{
"summary": "Implemented user authentication and fixed login bug"
}'
{
"id": "session-abc123",
"status": "completed"
}
Get Recent Sessions
GET /sessions/recent
Retrieve recent sessions, optionally filtered by project.
Query Parameters
Maximum number of sessions to return (1-100)
Response
Returns an array of session summaries:
ISO 8601 timestamp when session started
ISO 8601 timestamp when session ended (null if still active)
Session summary if provided
Number of observations in this session
Example
curl "http://127.0.0.1:7437/sessions/recent?project=engram&limit=3"
[
{
"id": "session-abc123",
"project": "engram",
"started_at": "2024-03-15 14:30:00",
"ended_at": "2024-03-15 16:45:00",
"summary": "Implemented user authentication",
"observation_count": 12
},
{
"id": "session-def456",
"project": "engram",
"started_at": "2024-03-14 10:00:00",
"ended_at": null,
"summary": null,
"observation_count": 5
}
]
Session Schema
Complete session object structure:
interface Session {
id: string;
project: string;
directory: string;
started_at: string; // ISO 8601
ended_at?: string | null; // ISO 8601
summary?: string | null;
}
interface SessionSummary {
id: string;
project: string;
started_at: string;
ended_at?: string | null;
summary?: string | null;
observation_count: number;
}