Intelligence API
Endpoints for reinforcing memories, extracting insights from conversations, and debugging retrieval behavior.
Reinforce Memory
POST
/v1/memories/{id}/reinforceProvide explicit feedback on a memory. Positive reinforcement strengthens it (+1), negative weakens it (-1). This is weighted 5× more than passive access.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
value | number | Yes | 1 (positive) or -1 (negative) |
reason | string | No | Optional reason for feedback |
Example Request
curl -X POST "https://fathippo.ai/api/v1/memories/mem_abc123/reinforce" \
-H "Authorization: Bearer mem_your_api_key" \
-H "Content-Type: application/json" \
-d '{"value": 1, "reason": "This preference was accurate"}'Response
{
"memoryId": "mem_abc123",
"feedbackScore": 3,
"accessCount": 15,
"newTier": "high",
"promoted": true,
"demoted": false,
"message": "Memory reinforced. Promoted to high tier."
}Tip
Use reinforcement when a memory was particularly helpful (or unhelpful). Memories with high feedback scores rank higher in search results.
Lock Tier
POST
/v1/memories/{id}/lockManually promote a memory to a specific tier and lock it there. Locked memories won't be auto-demoted by decay.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tier | string | Yes | critical | high | normal |
Example Request
curl -X POST "https://fathippo.ai/api/v1/memories/mem_abc123/lock" \
-H "Authorization: Bearer mem_your_api_key" \
-H "Content-Type: application/json" \
-d '{"tier": "critical"}'Response
{
"memoryId": "mem_abc123",
"tier": "critical",
"locked": true,
"message": "Memory locked at critical tier"
}Log Miss
POST
/v1/memories/missLog when a user asks about something your agent didn't know. Misses help identify gaps in memory coverage.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The query that had no good results |
sessionId | string | No | Session where miss occurred |
context | string | No | Additional context about the miss |
Example Request
curl -X POST "https://fathippo.ai/api/v1/memories/miss" \
-H "Authorization: Bearer mem_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"query": "What is the users favorite restaurant?",
"sessionId": "sess_xyz789",
"context": "User asked about dinner plans"
}'Response
{
"logged": true,
"missId": "miss_abc123"
}Get Misses
GET
/v1/memories/missesRetrieve logged misses to understand what memories you should be storing.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Max results |
since | ISO date | – | Filter by date |
Response
{
"misses": [
{
"id": "miss_abc123",
"query": "What is the users favorite restaurant?",
"context": "User asked about dinner plans",
"createdAt": "2026-03-04T10:00:00Z"
}
],
"count": 1
}Extract Memories
POST
/v1/extractAnalyze a conversation and extract suggested memories using heuristic pattern matching. Returns confidence scores for each suggestion.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
conversation | array | Yes | Array of {role, content} messages |
namespace | string | No | Target namespace for extracted memories |
Example Request
curl -X POST "https://fathippo.ai/api/v1/extract" \
-H "Authorization: Bearer mem_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"conversation": [
{"role": "user", "content": "My name is John and I live in Singapore"},
{"role": "assistant", "content": "Nice to meet you, John!"},
{"role": "user", "content": "I prefer morning meetings, usually around 9am"},
{"role": "assistant", "content": "Got it, I will remember that preference."}
]
}'Response
{
"suggestions": [
{
"title": "User Identity: My name is John and I live in Singapore",
"content": "My name is John and I live in Singapore",
"memoryType": "identity",
"suggestedTier": "critical",
"confidence": 0.95
},
{
"title": "User Preference: I prefer morning meetings, usually around 9am",
"content": "I prefer morning meetings, usually around 9am",
"memoryType": "preference",
"suggestedTier": "high",
"confidence": 0.92
}
],
"tokensAnalyzed": 156
}Note
Extraction uses pattern matching, not LLM calls. This keeps costs at zero while maintaining high accuracy for common memory types.
Explain Retrieval
POST
/v1/explainDebug why memories were or weren't retrieved for a query. Shows the full scoring breakdown for each result.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query to explain |
memoryId | string | No | Explain a specific memory |
threshold | number | No | Custom threshold (default: 0.7) |
topK | number | No | Max results to explain (default: 20) |
Example Request
curl -X POST "https://fathippo.ai/api/v1/explain" \
-H "Authorization: Bearer mem_your_api_key" \
-H "Content-Type: application/json" \
-d '{"query": "What timezone is the user in?"}'Response
{
"query": "What timezone is the user in?",
"threshold": 0.7,
"results": [
{
"memoryId": "mem_abc123",
"title": "User is based in Singapore",
"score": 0.923,
"vectorScore": 0.89,
"entityBonus": 0.0,
"feedbackBonus": 0.16,
"accessBonus": 0.08,
"included": true,
"reason": "Score 0.923 >= threshold 0.7"
},
{
"memoryId": "mem_xyz789",
"title": "User prefers morning meetings",
"score": 0.65,
"vectorScore": 0.62,
"entityBonus": 0.0,
"feedbackBonus": 0.0,
"accessBonus": 0.03,
"included": false,
"reason": "Score 0.650 < threshold 0.7"
}
],
"tokenEstimate": 45,
"breakdown": {
"vectorWeight": 1.0,
"entityWeight": 0.06,
"feedbackWeight": 0.08,
"accessWeight": 0.01,
"accessCap": 25
}
}Tip
Use explain to understand why a memory isn't appearing in results. If the vector score is low, the memory content may need to be rephrased. If bonuses are low, it may need more reinforcement.