Search API

Perform semantic search across your memories. Results are ranked by a combination of vector similarity, entity overlap, feedback score, and access frequency.

Semantic Search

POST/v1/search

Search memories using natural language. The query is embedded and compared against stored memory embeddings.

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language search query
`topK`	number	No	Number of results (default: 10, max: 50)
`namespace`	string	No	Filter by namespace
`since`	ISO date	No	Filter by creation date

Example Request

curl -X POST "https://fathippo.ai/api/v1/search" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What database does the user prefer?", "topK": 5}'

Response

[
  {
    "id": "mem_abc123",
    "score": 0.923,
    "vectorScore": 0.89,
    "provenance": {
      "source": "api",
      "createdAt": "2026-03-01T10:00:00Z"
    },
    "memory": {
      "id": "mem_abc123",
      "title": "User prefers PostgreSQL",
      "text": "User decided to use PostgreSQL for the new project because of team familiarity",
      "memoryType": "decision",
      "importanceTier": "high",
      "entities": ["PostgreSQL"],
      "accessCount": 8,
      "feedbackScore": 2,
      "createdAt": "2026-03-01T10:00:00Z"
    }
  }
]

Relevance Scoring

The final score is calculated from multiple factors:

score = vectorScore 
      + (entityOverlap × 0.06) 
      + (feedbackScore × 0.08)
      + (min(accessCount, 25) × 0.01)

Factor	Weight	Description
`Vector Similarity`	1.0	Cosine similarity between query and memory embeddings
`Entity Overlap`	0.06	Number of shared named entities
`Feedback Score`	0.08	Net positive/negative reinforcement
`Access Count`	0.01	Times retrieved (capped at 25)

Tip

Memories that are frequently accessed and have positive feedback will rank higher, even with slightly lower vector similarity. This creates a feedback loop where useful memories become easier to find.

Side Effects

Each search automatically:

Increments accessCount for returned memories
Records search hit patterns for analytics
Triggers auto-promotion checks (normal → high tier)

This means memories get stronger the more they're retrieved—similar to how human recall strengthens neural pathways.

Provenance

Each result includes provenance information showing where the memory came from:

Source	Description
`api`	Created via API
`pdf`	Extracted from uploaded PDF
`url`	Extracted from ingested URL
`mcp`	Created via MCP server

Semantic Search

POST/v1/search

Search memories using natural language. The query is embedded and compared against stored memory embeddings.

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language search query
`topK`	number	No	Number of results (default: 10, max: 50)
`namespace`	string	No	Filter by namespace
`since`	ISO date	No	Filter by creation date

Example Request

curl -X POST "https://fathippo.ai/api/v1/search" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What database does the user prefer?", "topK": 5}'

Response

[
  {
    "id": "mem_abc123",
    "score": 0.923,
    "vectorScore": 0.89,
    "provenance": {
      "source": "api",
      "createdAt": "2026-03-01T10:00:00Z"
    },
    "memory": {
      "id": "mem_abc123",
      "title": "User prefers PostgreSQL",
      "text": "User decided to use PostgreSQL for the new project because of team familiarity",
      "memoryType": "decision",
      "importanceTier": "high",
      "entities": ["PostgreSQL"],
      "accessCount": 8,
      "feedbackScore": 2,
      "createdAt": "2026-03-01T10:00:00Z"
    }
  }
]

Relevance Scoring

The final score is calculated from multiple factors:

score = vectorScore 
      + (entityOverlap × 0.06) 
      + (feedbackScore × 0.08)
      + (min(accessCount, 25) × 0.01)

Factor	Weight	Description
`Vector Similarity`	1.0	Cosine similarity between query and memory embeddings
`Entity Overlap`	0.06	Number of shared named entities
`Feedback Score`	0.08	Net positive/negative reinforcement
`Access Count`	0.01	Times retrieved (capped at 25)

Tip

Source

Description

api

Created via API

pdf

Extracted from uploaded PDF

url

Extracted from ingested URL

mcp

Created via MCP server