Memories API

Store, retrieve, list, and delete memories. The memories API supports both plaintext and pre-encrypted content.

Create Memory

POST/v1/memories

Store a new memory with automatic type classification, entity extraction, and embedding generation.

Request Body

Field	Type	Required	Description
`content`	string	Yes*	Memory content (plaintext)
`text`	string	Yes*	Alias for content
`title`	string	No	Title (auto-generated if omitted)
`memoryType`	string	No	Override type classification
`importanceTier`	string	No	critical \| high \| normal
`namespace`	string	No	Namespace for organization
`sessionId`	string	No	Link to active session
`metadata`	object	No	Arbitrary JSON metadata

* Either content or ciphertext+iv required

Example Request

curl -X POST "https://fathippo.ai/api/v1/memories" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User decided to use PostgreSQL for the new project",
    "importanceTier": "high",
    "namespace": "project-alpha"
  }'

Response (201 Created)

{
  "memory": {
    "id": "mem_abc123xyz",
    "title": "User decided to use PostgreSQL for the new project",
    "text": "User decided to use PostgreSQL for the new project",
    "memoryType": "decision",
    "importanceTier": "high",
    "entities": ["PostgreSQL"],
    "sourceType": "api",
    "createdAt": "2026-03-04T10:30:00Z"
  }
}

Consolidation Suggestion

If a similar memory exists (cosine similarity > 0.85), the API returns a consolidation suggestion instead of creating a duplicate:

{
  "status": "consolidation_suggested",
  "newMemory": {
    "title": "User prefers PostgreSQL",
    "text": "User prefers PostgreSQL",
    "memoryType": "preference",
    "importanceTier": "normal",
    "entities": ["PostgreSQL"]
  },
  "similarMemories": [
    {
      "id": "mem_existing123",
      "title": "User decided to use PostgreSQL",
      "text": "User decided to use PostgreSQL for the new project",
      "similarity": 0.91,
      "memoryType": "decision",
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "suggestion": "Consider merging with the existing memory",
  "hint": "Add ?force=true to create anyway"
}

Tip

To bypass consolidation, add ?force=true to the URL.

List Memories

GET/v1/memories

List memories with optional filtering.

Query Parameters

Parameter	Type	Default	Description
`namespace`	string	–	Filter by namespace
`limit`	number	50	Max results (max: 200)
`since`	ISO date	–	Filter by creation date

Example Request

curl "https://fathippo.ai/api/v1/memories?limit=10&namespace=project-alpha" \
  -H "Authorization: Bearer mem_your_api_key"

Response

{
  "memories": [
    {
      "id": "mem_abc123",
      "title": "User prefers dark mode",
      "text": "User prefers dark mode and concise responses",
      "memoryType": "preference",
      "importanceTier": "normal",
      "accessCount": 5,
      "feedbackScore": 0,
      "createdAt": "2026-03-01T10:00:00Z",
      "updatedAt": "2026-03-04T15:30:00Z"
    }
  ]
}

Get Single Memory

GET/v1/memories/{id}

Retrieve a single memory by ID.

Example Request

curl "https://fathippo.ai/api/v1/memories/mem_abc123" \
  -H "Authorization: Bearer mem_your_api_key"

Response

{
  "memory": {
    "id": "mem_abc123",
    "title": "User prefers dark mode",
    "text": "User prefers dark mode and concise responses",
    "memoryType": "preference",
    "importanceTier": "normal",
    "entities": ["dark mode"],
    "accessCount": 5,
    "feedbackScore": 0,
    "sourceType": "api",
    "createdAt": "2026-03-01T10:00:00Z",
    "updatedAt": "2026-03-04T15:30:00Z"
  }
}

Delete Memory

DELETE/v1/memories/{id}

Permanently delete a memory.

Example Request

curl -X DELETE "https://fathippo.ai/api/v1/memories/mem_abc123" \
  -H "Authorization: Bearer mem_your_api_key"

Response (200 OK)

{
  "deleted": true,
  "id": "mem_abc123"
}

Warning

Deletion is permanent and cannot be undone. The memory is removed from both the database and vector store.

Memory Types

FatHippo auto-classifies memories into types. You can override this with the memoryType field:

Type	Auto-Detection Patterns
`identity`	"I am", "my name is", "I'm called"
`preference`	"I prefer", "I like", "I always"
`constraint`	"must always", "never do", "required to"
`decision`	"decided", "going with", "we chose"
`fact`	"is located in", "works at", "my email is"
`how_to`	"the way to", "my process for"
`relationship`	"my wife", "my colleague", "my boss"
`event`	"yesterday", "last week", "we had a meeting"
`belief`	"I believe", "I think that", "my view is"

Memories API

Store, retrieve, list, and delete memories. The memories API supports both plaintext and pre-encrypted content.

Create Memory

POST/v1/memories

Store a new memory with automatic type classification, entity extraction, and embedding generation.

Request Body

Field	Type	Required	Description
`content`	string	Yes*	Memory content (plaintext)
`text`	string	Yes*	Alias for content
`title`	string	No	Title (auto-generated if omitted)
`memoryType`	string	No	Override type classification
`importanceTier`	string	No	critical \| high \| normal
`namespace`	string	No	Namespace for organization
`sessionId`	string	No	Link to active session
`metadata`	object	No	Arbitrary JSON metadata

* Either content or ciphertext+iv required

Example Request

curl -X POST "https://fathippo.ai/api/v1/memories" \
  -H "Authorization: Bearer mem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User decided to use PostgreSQL for the new project",
    "importanceTier": "high",
    "namespace": "project-alpha"
  }'

Response (201 Created)

{
  "memory": {
    "id": "mem_abc123xyz",
    "title": "User decided to use PostgreSQL for the new project",
    "text": "User decided to use PostgreSQL for the new project",
    "memoryType": "decision",
    "importanceTier": "high",
    "entities": ["PostgreSQL"],
    "sourceType": "api",
    "createdAt": "2026-03-04T10:30:00Z"
  }
}

Consolidation Suggestion

If a similar memory exists (cosine similarity > 0.85), the API returns a consolidation suggestion instead of creating a duplicate:

{
  "status": "consolidation_suggested",
  "newMemory": {
    "title": "User prefers PostgreSQL",
    "text": "User prefers PostgreSQL",
    "memoryType": "preference",
    "importanceTier": "normal",
    "entities": ["PostgreSQL"]
  },
  "similarMemories": [
    {
      "id": "mem_existing123",
      "title": "User decided to use PostgreSQL",
      "text": "User decided to use PostgreSQL for the new project",
      "similarity": 0.91,
      "memoryType": "decision",
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "suggestion": "Consider merging with the existing memory",
  "hint": "Add ?force=true to create anyway"
}

Tip

To bypass consolidation, add ?force=true to the URL.

List Memories

GET/v1/memories

List memories with optional filtering.

Query Parameters

Parameter	Type	Default	Description
`namespace`	string	–	Filter by namespace
`limit`	number	50	Max results (max: 200)
`since`	ISO date	–	Filter by creation date

Example Request

curl "https://fathippo.ai/api/v1/memories?limit=10&namespace=project-alpha" \
  -H "Authorization: Bearer mem_your_api_key"

Response

{
  "memories": [
    {
      "id": "mem_abc123",
      "title": "User prefers dark mode",
      "text": "User prefers dark mode and concise responses",
      "memoryType": "preference",
      "importanceTier": "normal",
      "accessCount": 5,
      "feedbackScore": 0,
      "createdAt": "2026-03-01T10:00:00Z",
      "updatedAt": "2026-03-04T15:30:00Z"
    }
  ]
}

Get Single Memory

GET/v1/memories/{id}

Retrieve a single memory by ID.

Example Request

curl "https://fathippo.ai/api/v1/memories/mem_abc123" \
  -H "Authorization: Bearer mem_your_api_key"

Response

{
  "memory": {
    "id": "mem_abc123",
    "title": "User prefers dark mode",
    "text": "User prefers dark mode and concise responses",
    "memoryType": "preference",
    "importanceTier": "normal",
    "entities": ["dark mode"],
    "accessCount": 5,
    "feedbackScore": 0,
    "sourceType": "api",
    "createdAt": "2026-03-01T10:00:00Z",
    "updatedAt": "2026-03-04T15:30:00Z"
  }
}

Delete Memory

DELETE/v1/memories/{id}

Permanently delete a memory.

Example Request

curl -X DELETE "https://fathippo.ai/api/v1/memories/mem_abc123" \
  -H "Authorization: Bearer mem_your_api_key"

Response (200 OK)

{
  "deleted": true,
  "id": "mem_abc123"
}

Warning

Deletion is permanent and cannot be undone. The memory is removed from both the database and vector store.

Memory Types

FatHippo auto-classifies memories into types. You can override this with the memoryType field:

Type	Auto-Detection Patterns
`identity`	"I am", "my name is", "I'm called"
`preference`	"I prefer", "I like", "I always"
`constraint`	"must always", "never do", "required to"
`decision`	"decided", "going with", "we chose"
`fact`	"is located in", "works at", "my email is"
`how_to`	"the way to", "my process for"
`relationship`	"my wife", "my colleague", "my boss"
`event`	"yesterday", "last week", "we had a meeting"
`belief`	"I believe", "I think that", "my view is"