Sessions API

Sessions track conversations from start to end. They provide initial context, track memory usage per turn, and enable analytics on conversation patterns.

Start Session

POST/v1/sessions/start

Start a new session and receive initial context. Critical memories are always injected, plus relevant high-tier memories based on the first message.

Request Body

Field	Type	Required	Description
`firstMessage`	string	No	First user message (for context relevance)
`namespace`	string	No	Namespace for session
`metadata`	object	No	Arbitrary session metadata

Example Request

curl -X POST "https://fathippo.ai/api/v1/sessions/start" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstMessage": "Help me design a REST API",
    "namespace": "project-alpha"
  }'

Response (201 Created)

{
  "sessionId": "sess_xyz789",
  "context": {
    "critical": [
      {
        "id": "mem_c1",
        "title": "User is John, software engineer",
        "text": "User is John, a software engineer based in Singapore",
        "type": "identity"
      }
    ],
    "high": [
      {
        "id": "mem_h1",
        "title": "User prefers REST over GraphQL",
        "text": "User chose REST over GraphQL because team is more familiar with it",
        "type": "decision"
      }
    ]
  },
  "stats": {
    "tokensInjected": 156,
    "criticalCount": 1,
    "highCount": 1
  }
}

Tip

The context object contains memories formatted for injection into your AI's system prompt. Critical memories are your user's identity layer— always include them.

Record Turn

POST/v1/sessions/{id}/turn

Record a conversation turn. Returns a refresh signal every 5 turns with updated context for topic drift.

Request Body

Field	Type	Required	Description
`messages`	array	Yes	Array of {role, content} message objects
`turnNumber`	number	No	Turn number (auto-incremented if omitted)
`memoriesUsed`	string[]	No	IDs of memories used in this turn

Example Request

curl -X POST "https://fathippo.ai/api/v1/sessions/sess_xyz789/turn" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "turnNumber": 1,
    "messages": [
      {"role": "user", "content": "Help me design a REST API"},
      {"role": "assistant", "content": "Based on your preference for REST..."}
    ],
    "memoriesUsed": ["mem_h1"]
  }'

Response

{
  "turnNumber": 1,
  "refreshNeeded": false,
  "memoriesUsed": ["mem_h1"]
}

Context Refresh

Every 5 turns, refreshNeeded is true and a newContext object is returned with updated relevant memories:

{
  "turnNumber": 5,
  "refreshNeeded": true,
  "newContext": {
    "critical": [...],
    "high": [
      {
        "id": "mem_new",
        "title": "Project uses FastAPI",
        "text": "User mentioned they're building with FastAPI",
        "type": "fact"
      }
    ]
  },
  "memoriesUsed": ["mem_h1", "mem_h2"]
}

End Session

POST/v1/sessions/{id}/end

End a session and record the outcome. This updates analytics and can trigger memory extraction from the conversation.

Request Body

Field	Type	Required	Description
`outcome`	string	No	success \| partial \| failure \| abandoned
`summary`	string	No	Brief summary of the conversation
`extractMemories`	boolean	No	Auto-extract memories from conversation

Example Request

curl -X POST "https://fathippo.ai/api/v1/sessions/sess_xyz789/end" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "success",
    "summary": "Helped user design REST API endpoints"
  }'

Response

{
  "sessionId": "sess_xyz789",
  "ended": true,
  "duration": 342,
  "turnCount": 8,
  "memoriesUsed": 5,
  "outcome": "success"
}

List Sessions

GET/v1/sessions

List recent sessions with basic stats.

Example Request

curl "https://fathippo.ai/api/v1/sessions?limit=10" \
  -H "Authorization: Bearer mem_your_api_key"

Response

{
  "sessions": [
    {
      "id": "sess_xyz789",
      "startedAt": "2026-03-04T10:00:00Z",
      "endedAt": "2026-03-04T10:05:42Z",
      "turnCount": 8,
      "memoriesUsed": 5,
      "outcome": "success"
    }
  ]
}

Note

Sessions without an explicit end are auto-closed after 2 hours of inactivity. These are marked with outcome: "abandoned".

Sessions API

Sessions track conversations from start to end. They provide initial context, track memory usage per turn, and enable analytics on conversation patterns.

Start Session

POST/v1/sessions/start

Start a new session and receive initial context. Critical memories are always injected, plus relevant high-tier memories based on the first message.

Request Body

Field	Type	Required	Description
`firstMessage`	string	No	First user message (for context relevance)
`namespace`	string	No	Namespace for session
`metadata`	object	No	Arbitrary session metadata

Example Request

curl -X POST "https://fathippo.ai/api/v1/sessions/start" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstMessage": "Help me design a REST API",
    "namespace": "project-alpha"
  }'

Response (201 Created)

{
  "sessionId": "sess_xyz789",
  "context": {
    "critical": [
      {
        "id": "mem_c1",
        "title": "User is John, software engineer",
        "text": "User is John, a software engineer based in Singapore",
        "type": "identity"
      }
    ],
    "high": [
      {
        "id": "mem_h1",
        "title": "User prefers REST over GraphQL",
        "text": "User chose REST over GraphQL because team is more familiar with it",
        "type": "decision"
      }
    ]
  },
  "stats": {
    "tokensInjected": 156,
    "criticalCount": 1,
    "highCount": 1
  }
}

Tip

The context object contains memories formatted for injection into your AI's system prompt. Critical memories are your user's identity layer— always include them.

Record Turn

POST/v1/sessions/{id}/turn

Record a conversation turn. Returns a refresh signal every 5 turns with updated context for topic drift.

Request Body

Field	Type	Required	Description
`messages`	array	Yes	Array of {role, content} message objects
`turnNumber`	number	No	Turn number (auto-incremented if omitted)
`memoriesUsed`	string[]	No	IDs of memories used in this turn

Example Request

curl -X POST "https://fathippo.ai/api/v1/sessions/sess_xyz789/turn" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "turnNumber": 1,
    "messages": [
      {"role": "user", "content": "Help me design a REST API"},
      {"role": "assistant", "content": "Based on your preference for REST..."}
    ],
    "memoriesUsed": ["mem_h1"]
  }'

Response

{
  "turnNumber": 1,
  "refreshNeeded": false,
  "memoriesUsed": ["mem_h1"]
}

Context Refresh

Every 5 turns, refreshNeeded is true and a newContext object is returned with updated relevant memories:

{
  "turnNumber": 5,
  "refreshNeeded": true,
  "newContext": {
    "critical": [...],
    "high": [
      {
        "id": "mem_new",
        "title": "Project uses FastAPI",
        "text": "User mentioned they're building with FastAPI",
        "type": "fact"
      }
    ]
  },
  "memoriesUsed": ["mem_h1", "mem_h2"]
}

End Session

POST/v1/sessions/{id}/end

End a session and record the outcome. This updates analytics and can trigger memory extraction from the conversation.

Request Body

Field	Type	Required	Description
`outcome`	string	No	success \| partial \| failure \| abandoned
`summary`	string	No	Brief summary of the conversation
`extractMemories`	boolean	No	Auto-extract memories from conversation

Example Request

curl -X POST "https://fathippo.ai/api/v1/sessions/sess_xyz789/end" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "success",
    "summary": "Helped user design REST API endpoints"
  }'

Response

{
  "sessionId": "sess_xyz789",
  "ended": true,
  "duration": 342,
  "turnCount": 8,
  "memoriesUsed": 5,
  "outcome": "success"
}

List Sessions

GET/v1/sessions

List recent sessions with basic stats.

Example Request

curl "https://fathippo.ai/api/v1/sessions?limit=10" \
  -H "Authorization: Bearer mem_your_api_key"

Response

{
  "sessions": [
    {
      "id": "sess_xyz789",
      "startedAt": "2026-03-04T10:00:00Z",
      "endedAt": "2026-03-04T10:05:42Z",
      "turnCount": 8,
      "memoriesUsed": 5,
      "outcome": "success"
    }
  ]
}

Note

Sessions without an explicit end are auto-closed after 2 hours of inactivity. These are marked with outcome: "abandoned".