ZeroMemory API Reference

Base URL: https://api.ainative.studio/api/v1/public/memory/v2

All endpoints require Authorization: Bearer <token>.

---

POST /remember

Store a memory. Auto-generates embeddings, extracts entities, assigns importance scores.

Request:

{
  "content": "Alice is the CTO of AINative. She prefers Python.",
  "entity_id": "alice-johnson",
  "memory_type": "episodic",
  "importance": 0.8,
  "tags": ["team", "preferences"],
  "metadata": {"source": "onboarding"}
}

Field	Type	Default	Description
content	string	required	Memory text content
entity_id	string	null	Entity this memory is about
memory_type	string	"episodic"	working, episodic, or semantic
importance	float	0.5	0.0-1.0 importance score
tags	string[]	null	Tags for categorization
metadata	object	null	Arbitrary metadata

Response:

{
  "memory_id": "mem_abc123",
  "content": "Alice is the CTO of AINative...",
  "importance": 0.8,
  "memory_type": "episodic",
  "entities_extracted": ["Alice", "AINative", "Python"],
  "next_steps": {
    "action": "recall",
    "suggestion": "Memory stored. Recall it by meaning using /recall.",
    "endpoint": "POST /api/v1/public/memory/v2/recall"
  }
}

---

POST /recall

Search memories by meaning. Returns scored, ranked results using blended scoring (similarity + importance + recency).

Supports two opt-in LLM enhancements: query expansion (runs semantic variants in parallel, merges results) and LLM reranking (Qwen relevance judge reorders results and adds llm_relevance scores).

Request:

{
  "query": "Who is the CTO?",
  "entity_id": "alice-johnson",
  "layer": "episodic",
  "limit": 5,
  "query_expansion": false,
  "rerank": false
}

Field	Type	Default	Description
query	string	required	Natural language search query
entity_id	string	null	Filter by entity
layer	string	null	Filter: working, episodic, semantic
limit	int	10	1-100 max results
as_of	datetime	null	Historical recall — return memories valid at this timestamp
query_expansion	bool	false	LLM expands query into variants, runs in parallel, merges by best score
rerank	bool	false	LLM relevance judge reorders results; adds llm_relevance field (0-1)

Response:

{
  "results": [
    {
      "memory_id": "mem_abc123",
      "content": "Alice is the CTO of AINative. She prefers Python.",
      "score": 0.94,
      "llm_relevance": 0.91,
      "importance": 0.8,
      "memory_type": "episodic",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ],
  "count": 1,
  "query_expansion": false,
  "reranked": false
}

LLM enhancements

query_expansion: true runs 3 semantic variants in parallel and merges by best score — useful for ambiguous queries. rerank: true adds llm_relevance (0–1) to each result and reorders by it. Both use the self-hosted Qwen model, no extra cost.

---

DELETE /forget/{memory_id}

Delete a specific memory by ID.

curl -X DELETE https://api.ainative.studio/api/v1/public/memory/v2/forget/mem_abc123 \
  -H "Authorization: Bearer $TOKEN"

POST /forget

Delete a memory by ID using a request body. Useful when the ID contains special characters or you prefer body-based requests.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/forget \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memory_id": "mem_abc123"}'

---

POST /reflect/{entity_id}

Generate insights by reflecting on an entity's memories. Uses LLM to synthesize patterns.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/reflect/alice-johnson \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "entity_id": "alice-johnson",
  "reflection": "Alice is the CTO, prefers Python, focuses on backend architecture...",
  "memory_count": 15,
  "key_themes": ["leadership", "python", "architecture"]
}

POST /reflect

Reflect on an entity using a request body.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/reflect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "alice-johnson"}'

---

GET /profile/{entity_id}

Get a consolidated profile built from all memories about an entity.

curl https://api.ainative.studio/api/v1/public/memory/v2/profile/alice-johnson \
  -H "Authorization: Bearer $TOKEN"

POST /profile

Get an entity profile using a request body.

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "alice-johnson"}'

---

POST /relate

Store a typed relationship between two entities.

Request:

{
  "subject": "Alice Johnson",
  "predicate": "manages",
  "object": "Backend Team",
  "confidence": 0.9
}

Field	Type	Default	Description
subject	string	required	Source entity
predicate	string	required	Relationship type
object	string	required	Target entity
confidence	float	0.8	0.0-1.0 confidence

---

GET /graph/{entity_id}

Get all relationships for an entity.

curl "https://api.ainative.studio/api/v1/public/memory/v2/graph/alice-johnson?limit=50" \
  -H "Authorization: Bearer $TOKEN"

---

GET /entities

List entities auto-extracted from stored memories.

curl "https://api.ainative.studio/api/v1/public/memory/v2/entities?entity_type=person&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Parameter	Type	Default	Description
user_id	UUID	caller	Filter by owner
entity_type	string	null	person, org, tech, concept
limit	int	100	1-500 max results

---

GET /entities/{entity_id}/timeline

Get the chronological fact history for an entity. Returns all graph edges ordered by valid_from. Superseded facts include valid_until and status: "superseded"; current facts have status: "current".

Useful for answering temporal questions like: "Where did Alice work in 2024?"

curl "https://api.ainative.studio/api/v1/public/memory/v2/entities/alice-johnson/timeline" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "entity_id": "alice-johnson",
  "edges": [
    {
      "predicate": "works_at",
      "object": "Startup Inc",
      "valid_from": "2022-01-01T00:00:00Z",
      "valid_until": "2024-06-01T00:00:00Z",
      "status": "superseded"
    },
    {
      "predicate": "works_at",
      "object": "AINative",
      "valid_from": "2024-06-01T00:00:00Z",
      "valid_until": null,
      "status": "current"
    }
  ]
}

---

DELETE /entities/{entity_id}

Forget an entity and its graph edges.

• cascade=false (default): removes entity node + all its edges only
• cascade=true: also removes all memories that mention this entity

Returns counts of what was removed. All deletes are in a single transaction.

# Remove entity only
curl -X DELETE "https://api.ainative.studio/api/v1/public/memory/v2/entities/alice-johnson" \
  -H "Authorization: Bearer $TOKEN"

# Remove entity + all related memories
curl -X DELETE "https://api.ainative.studio/api/v1/public/memory/v2/entities/alice-johnson?cascade=true" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "entity_id": "alice-johnson",
  "edges_removed": 12,
  "memories_removed": 0,
  "cascade": false
}

---

POST /process

Auto-extract memories from a conversation transcript using NLP. Parses messages and stores any facts, preferences, or relationships discovered.

Request:

{
  "messages": [
    {"role": "user", "content": "I'm Alice, CTO at AINative. I prefer Python."},
    {"role": "assistant", "content": "Got it! I'll remember that."}
  ],
  "entity_id": "alice-johnson"
}

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "I am Alice, CTO of AINative"}],
    "entity_id": "alice-johnson"
  }'

Response:

{
  "memories_extracted": 3,
  "memories": [
    {"memory_id": "mem_001", "content": "Alice is CTO at AINative", "memory_type": "semantic"},
    {"memory_id": "mem_002", "content": "Alice prefers Python", "memory_type": "episodic"}
  ]
}

---

Temporal Recall with as_of

The /recall endpoint supports historical queries via the as_of parameter. Returns only memories whose graph edges were valid at that timestamp.

{
  "query": "Where did Alice work?",
  "entity_id": "alice-johnson",
  "as_of": "2023-06-01T00:00:00Z"
}

---

POST /context

Retrieve relevant memories and synthesize them into a single, ready-to-use context string via the AINative inference API. Ideal for injecting grounded context into agent prompts.

Request:

{
  "query": "What pricing decisions did we make last quarter?",
  "agent_id": "agent-001",
  "synthesis_style": "bullet",
  "top_k": 10,
  "max_tokens": 1500,
  "query_expansion": false,
  "rerank": false
}

Field	Type	Default	Description
query	string	required	Question or topic to synthesize context for
agent_id	string	null	Scope retrieval to this agent
synthesis_style	string	"narrative"	narrative | bullet | structured
top_k	int	10	Memories to retrieve before synthesis (1-50)
max_tokens	int	2000	Target max tokens for synthesized output
query_expansion	bool	false	LLM-expand query before retrieval
rerank	bool	false	Rerank by LLM relevance before synthesis

Response:

{
  "context": "• Alice is CTO at AINative\n• Pro tier pricing: $49/mo (set Q1 2026)\n• Enterprise pricing: per-seat",
  "query": "What pricing decisions did we make last quarter?",
  "confidence": 0.8833,
  "token_count": 47,
  "sources": [
    {
      "memory_id": "mem_abc123",
      "score": 0.92,
      "content_snippet": "Pro tier pricing set to $49/mo..."
    }
  ]
}

Synthesis styles:

Style	Output
narrative	Flowing prose: "Alice is CTO of AINative. Pricing was set to $49/mo in Q1..."
bullet	Bullet points: "• Alice: CTO\n• Pro tier: $49/mo\n• Enterprise: per-seat"
structured	Labeled fields: "Role: CTO\nPricing: $49/mo (Pro)\nEnterprise: per-seat"

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/context \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "What pricing decisions did we make?", "agent_id": "agent-001", "synthesis_style": "bullet"}'

---

Write-Back Actions

Native write-back tools using stored OAuth tokens from your connected accounts. No separate API keys needed — connect your account once via the Connections API, then use these endpoints.

POST /actions/slack/send

Field	Type	Description
channel	string	Channel name (#general) or ID
message	string	Message text (Slack mrkdwn)
thread_ts	string	Optional — reply in thread

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/slack/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "#alerts", "message": "Deploy finished at 14:32 UTC"}'

Response: {"ts": "1234567890.123456", "channel": "C123ABC", "message": "Message sent successfully"}

POST /actions/gmail/reply

Field	Type	Description
thread_id	string	Gmail thread ID
body	string	Reply body (plain text or HTML)
cc	string[]	Optional CC recipients

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/gmail/reply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"thread_id": "18abc123", "body": "Done — see attached report."}'

POST /actions/calendar/create

Field	Type	Description
title	string	Event title
start	string	ISO 8601 start datetime
end	string	ISO 8601 end datetime
description	string	Optional description
attendees	string[]	Optional attendee emails
calendar_id	string	Calendar ID (default: primary)

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/calendar/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint Planning", "start": "2026-05-05T10:00:00-07:00", "end": "2026-05-05T11:00:00-07:00"}'

Response: {"id": "event_abc", "html_link": "https://calendar.google.com/...", "message": "Event created successfully"}

POST /actions/github/issue

Field	Type	Description
repo	string	owner/repo format
title	string	Issue title
body	string	Issue body (markdown)
labels	string[]	Optional label names

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/github/issue \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "acme/backend", "title": "Memory leak in recall", "labels": ["bug"]}'

Response: {"number": 123, "html_url": "https://github.com/acme/backend/issues/123", "message": "Issue created successfully"}

POST /actions/notion/page

Field	Type	Description
parent_id	string	Parent page or database UUID
title	string	Page title
content	string	Content (plain text or markdown, auto-converted to blocks)

curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/notion/page \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent_id": "your-parent-uuid", "title": "Sprint Notes", "content": "## Goals\n- Ship context synthesis"}'

Response: {"id": "page-uuid", "url": "https://notion.so/...", "message": "Page created successfully"}

---

Endpoint Summary

Method	Path	Description
POST	/remember	Store a memory
POST	/recall	Semantic search (query_expansion, rerank, as_of supported)
DELETE	/forget/{id}	Delete a memory by path param
POST	/forget	Delete a memory by body
POST	/reflect/{entity_id}	Generate insights (path param)
POST	/reflect	Generate insights (body)
GET	/profile/{entity_id}	Entity profile (path param)
POST	/profile	Entity profile (body)
POST	/relate	Store relationship
GET	/graph/{entity_id}	Entity relationships
GET	/entities	List extracted entities
GET	/entities/{entity_id}/timeline	Chronological fact history
DELETE	/entities/{entity_id}	Forget entity (cascade optional)
POST	/process	Auto-extract memories from conversation
POST	/context	LLM-synthesize memories into context string
POST	/actions/slack/send	Send Slack message via stored OAuth token
POST	/actions/gmail/reply	Reply to Gmail thread
POST	/actions/calendar/create	Create Google Calendar event
POST	/actions/github/issue	Create GitHub issue
POST	/actions/notion/page	Create Notion page

For knowledge graph endpoints (traverse, GraphRAG, ontology), see the Context Graph API.