Session Management API — Start, End, and List Sessions

Sessions represent a single agent conversation. Start a session to receive relevant context recalled from past memories, and end it to trigger the consolidation pipeline that turns raw observations into structured long-term memory. Every observation captured during a session is scoped to its session ID.

POST /agentmemory/session/start

Starts a new session and returns a context block recalled from past memories. The context field is ready to inject directly into the agent’s first turn.

You must pass sessionId, project, and cwd — Agent Memory uses cwd to scope the project profile and rank relevant memories by path proximity.

Request

curl -X POST http://localhost:3111/agentmemory/session/start \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "project": "my-project",
    "cwd": "/home/user/projects/my-project",
    "agentId": "claude-code"
  }'

{
  "sessionId": "sess_abc123",
  "project": "my-project",
  "cwd": "/home/user/projects/my-project",
  "agentId": "claude-code"
}

sessionId

string

required

A unique identifier for this session. Generate a UUID or use your agent’s native session ID. Used to scope observations and link memories back to the session.

project

string

required

Project name or identifier. Agent Memory uses this to scope the memory profile and recall only relevant past context.

cwd

string

required

Working directory path for the session. Used to rank memories by file path proximity and build the project profile.

agentId

string

Agent identifier for scoped memory. In multi-agent setups, set this to the agent’s role (e.g. "architect", "developer", "reviewer"). Falls back to the AGENT_ID environment variable on the server. When AGENTMEMORY_AGENT_SCOPE=isolated, only memories tagged with this agentId are recalled.

title

string

Optional title for this session, stored as both summary and firstPrompt. Useful for labelling sessions when replaying them later in the viewer.

Response

{
  "session": {
    "id": "sess_abc123",
    "project": "my-project",
    "cwd": "/home/user/projects/my-project",
    "startedAt": "2025-01-15T10:30:00.000Z",
    "status": "active",
    "observationCount": 0,
    "agentId": "claude-code"
  },
  "context": "## Previous Session Context\n\nAuth uses JWT middleware in src/middleware/auth.ts.\nYou chose jose over jsonwebtoken for Edge compatibility.\n\n..."
}

session

object

The full session object as stored. Includes id, project, cwd, startedAt, status (active), and observationCount (starts at 0).

context

string

Recalled memories formatted as a human-readable context block. Inject this into the agent’s first turn. Empty string if no relevant memories exist yet.

POST /agentmemory/session/end

Ends an active session and fans out the session-stopped lifecycle event. This triggers the consolidation pipeline asynchronously — sessions are summarised, knowledge graph nodes are extracted (if GRAPH_EXTRACTION_ENABLED=true), and slot reflection runs (if AGENTMEMORY_REFLECT=true).

Request

curl -X POST http://localhost:3111/agentmemory/session/end \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "sess_abc123" }'

sessionId

string

required

The session ID returned by /session/start. The session’s status is set to completed and endedAt is recorded.

Response

{ "success": true }

The consolidation pipeline runs asynchronously after the response is returned — the 200 response does not mean consolidation is complete.

GET /agentmemory/sessions

Lists all sessions. By default, returns all sessions visible to the current agent scope. Filter by agentId query param for multi-agent setups.

Request

curl "http://localhost:3111/agentmemory/sessions?agentId=claude-code"

Query param	Type	Description
`agentId`	string	Filter sessions by agent. Pass `*` to bypass scope isolation and see all agents’ sessions.

Response

{
  "sessions": [
    {
      "id": "sess_abc123",
      "project": "my-project",
      "cwd": "/home/user/projects/my-project",
      "startedAt": "2025-01-15T10:30:00.000Z",
      "endedAt": "2025-01-15T11:45:00.000Z",
      "status": "completed",
      "observationCount": 47,
      "agentId": "claude-code",
      "summary": "Implemented JWT refresh token rotation",
      "commitShas": ["a1b2c3d"]
    }
  ]
}

sessions

Session[]

Array of session objects sorted by startedAt descending. Each session includes id, project, cwd, startedAt, endedAt (if ended), status (active | completed | abandoned), observationCount, agentId, summary, and commitShas.

GET /agentmemory/observations

Lists compressed observations for a specific session. Observations are the processed, deduplicated records captured from hook events during the session.

Request

curl "http://localhost:3111/agentmemory/observations?sessionId=sess_abc123"

Query param	Type	Description
`sessionId`	string (required)	The session to retrieve observations for.
`agentId`	string	Filter by agent ID. Pass `*` to bypass scope isolation.

Response

{
  "observations": [
    {
      "id": "obs_xyz",
      "sessionId": "sess_abc123",
      "timestamp": "2025-01-15T10:35:00.000Z",
      "type": "file_write",
      "title": "Wrote JWT refresh token rotation logic",
      "facts": ["Added rotateRefreshToken() to src/auth/tokens.ts", "Uses 7-day sliding window"],
      "narrative": "The agent wrote a refresh token rotation function...",
      "concepts": ["auth", "JWT", "refresh-token"],
      "files": ["src/auth/tokens.ts"],
      "importance": 0.82
    }
  ]
}

POST /agentmemory/observe

Captures a raw observation directly — without going through a full session lifecycle. Use this from custom integrations, scripts, or agents that manage their own hook dispatch.

You must provide sessionId, project, cwd, hookType, and timestamp — all are required. The observation will not be captured if any of these fields are missing or empty.

Request

curl -X POST http://localhost:3111/agentmemory/observe \
  -H "Content-Type: application/json" \
  -d '{
    "hookType": "post_tool_use",
    "sessionId": "sess_abc123",
    "project": "my-project",
    "cwd": "/home/user/projects/my-project",
    "timestamp": "2025-01-15T10:35:00.000Z",
    "data": {
      "toolName": "Read",
      "toolInput": { "file_path": "src/auth/tokens.ts" },
      "toolOutput": "// JWT refresh token implementation..."
    }
  }'

hookType

string

required

The lifecycle event type. One of: session_start, prompt_submit, pre_tool_use, post_tool_use, post_tool_failure, pre_compact, subagent_start, subagent_stop, notification, task_completed, stop, session_end.

sessionId

string

required

Session ID to attach this observation to.

project

string

required

Project name for scoping.

cwd

string

required

Working directory path.

timestamp

string

required

ISO 8601 timestamp for when the event occurred.

data

object

The raw event payload. For tool-use hooks, include toolName, toolInput, and toolOutput. For conversation hooks, include userPrompt and assistantResponse.

Response

Returns 201 with the result of the observation pipeline, including whether the observation was deduplicated (SHA-256 content dedup runs within a 5-minute window) or successfully compressed.

POST /agentmemory/session/commit

Links a Git commit SHA to a session. Agent Memory uses these links to display commit history in the viewer and to surface commit-scoped context in searches.

Request

curl -X POST http://localhost:3111/agentmemory/session/commit \
  -H "Content-Type: application/json" \
  -d '{
    "sha": "a1b2c3d4e5f6...",
    "sessionId": "sess_abc123",
    "branch": "feat/jwt-refresh",
    "message": "feat: add refresh token rotation",
    "author": "dev@example.com",
    "files": ["src/auth/tokens.ts", "test/auth.test.ts"]
  }'

sha

string

required

Full or short commit SHA.

sessionId

string

Session ID to link this commit to. A commit can be linked to multiple sessions — multiple calls with the same SHA merge their session IDs.

branch

string

Branch name.

message

string

Commit message.

files

string[]

Files changed in the commit.

Response

{
  "commit": {
    "sha": "a1b2c3d4e5f6...",
    "shortSha": "a1b2c3d",
    "branch": "feat/jwt-refresh",
    "message": "feat: add refresh token rotation",
    "sessionIds": ["sess_abc123"],
    "linkedAt": "2025-01-15T12:00:00.000Z"
  }
}

GET /agentmemory/session/by-commit

Looks up all sessions associated with a given commit SHA.

curl "http://localhost:3111/agentmemory/session/by-commit?sha=a1b2c3d"

Returns { "commit": CommitLink, "sessions": Session[] }, or 404 if no sessions are linked to that SHA.

POST /agentmemory/summarize

Manually triggers session summarization for an already-ended session. Useful if the automatic stop-hook pipeline was skipped or failed.

curl -X POST http://localhost:3111/agentmemory/summarize \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "sess_abc123" }'

​POST /agentmemory/session/start

​Request

​Response

​POST /agentmemory/session/end

​Request

​Response

​GET /agentmemory/sessions

​Request

​Response

​GET /agentmemory/observations

​Request

​Response

​POST /agentmemory/observe

​Request

​Response

​POST /agentmemory/session/commit

​Request

​Response

​GET /agentmemory/session/by-commit

​POST /agentmemory/summarize

POST /agentmemory/session/start

Request

Response

POST /agentmemory/session/end

Request

Response

GET /agentmemory/sessions

Request

Response

GET /agentmemory/observations

Request

Response

POST /agentmemory/observe

Request

Response

POST /agentmemory/session/commit

Request

Response

GET /agentmemory/session/by-commit

POST /agentmemory/summarize