Memory API

Core endpoints for storing, retrieving, and managing memories. These endpoints power the memory system that gives your AI persistent context across sessions.

POST/memory/ingest

Ingest Memories

Store new memories from conversations, documents, or manual input. Includes automatic deduplication to prevent storing duplicate memories.

Scope: write

Request Body

Parameter	Type	Required	Description
userId	`string`	Optional	User ID from your system. Links memories to a specific user.
tenantId	`string`	Optional	Tenant organization ID for multi-tenant apps.
messages	`Message[]`	Optional	Array of conversation messages to extract memories from.
content	`string`	Optional	Raw text content (documents, notes, any text).
title	`string`	Optional	Title for document content.
sourceUrl	`string`	Optional	Source URL for document content.
isDocument	`boolean`	Optional	Mark as document source for filtering in recall.Default: false
source	`object`	Optional	Source metadata: type, id, context.
memories	`Memory[]`	Optional	Pre-extracted memories (for manual source).

Input Formats

You can provide either messages (for conversations), content (for documents/text), or memories (for pre-extracted data).

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/ingest \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "messages": [
      {"role": "user", "content": "My name is Alex and I prefer dark mode."},
      {"role": "assistant", "content": "Nice to meet you, Alex! I\'ve noted your preference."}
    ]
  }'

Response

{
  "success": true,
  "data": {
    "memoriesAdded": 2,
    "memoriesUpdated": 0,
    "memoriesSkipped": 0,
    "memoryIds": ["mem_1735689600000_abc123", "mem_1735689600001_def456"],
    "tasksAdded": 0,
    "taskIds": [],
    "processingTimeMs": 523
  }
}

POST/memory/recall

Recall Memories

Semantic search with three-factor scoring: recency, importance, and relevance. Returns the most relevant memories for your query.

Scope: read

Request Body

Parameter	Type	Required	Description
query	`string`	Required	Natural language query to search for.
userId	`string`	Optional	User ID to scope the search.
tenantId	`string`	Optional	Tenant organization ID.
topK	`number`	Optional	Number of results to return.Default: 30
orgWide	`boolean`	Optional	Search across all users (admin only).Default: false
filters	`object`	Optional	Filter by rings, domains, categories, importance, age, tags.
weights	`object`	Optional	Custom scoring weights: recency, importance, relevance.
decisionsOnly	`boolean`	Optional	Only return decision memories.
decisionFilters	`object`	Optional	Filter by outcome, isException, isPrecedent.

Filter Options

Filter	Type	Values
rings	`string[]`	episodic, semantic, procedural
domains	`string[]`	work, finance, projects, goals, relationships, lifestyle, health, interests, calendar, tasks, resources, thinking, communication, context
minImportance	`number`	1-10
maxAgeDays	`number`	Number of days to look back
excludeDocuments	`boolean`	Exclude document-sourced memories
documentsOnly	`boolean`	Only return document-sourced memories

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/recall \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "query": "user preferences and settings",
    "topK": 10,
    "filters": {
      "rings": ["procedural"],
      "minImportance": 5
    }
  }'

Response

{
  "success": true,
  "data": {
    "memories": [
      {
        "memoryId": "mem_1735689600000_abc123",
        "content": "User prefers dark mode for all applications.",
        "ring": "procedural",
        "domain": "lifestyle",
        "category": "preference",
        "importance": 6,
        "confidence": 0.95,
        "createdAt": "2025-01-01T00:00:00.000Z",
        "tags": ["preferences", "ui"],
        "score": 0.87,
        "scoreBreakdown": {
          "recency": 0.9,
          "importance": 0.6,
          "relevance": 0.92
        }
      }
    ],
    "totalSearched": 150,
    "searchTimeMs": 45
  }
}

POST/memory/recent

Recent Memories

Get recent memories sorted by creation time (newest first). No semantic search - directly queries by timestamp for fast results.

Scope: read

Request Body

Parameter	Type	Required	Description
userId	`string`	Optional	User ID to scope the search.
tenantId	`string`	Optional	Tenant organization ID.
limit	`number`	Optional	Number of results to return (1-500).Default: 30
since	`string`	Optional	Time filter: 24h, 7d, 30d, or 90d.
filters	`object`	Optional	Filter by rings and domains.
orgWide	`boolean`	Optional	Search across all users (admin only).Default: false

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/recent \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "limit": 20,
    "since": "7d"
  }'

Response

{
  "success": true,
  "data": {
    "memories": [
      {
        "memoryId": "mem_1735689600000_abc123",
        "content": "User completed the onboarding tutorial.",
        "ring": "episodic",
        "domain": "projects",
        "category": "milestone",
        "importance": 5,
        "createdAt": "2025-01-01T12:00:00.000Z",
        "tags": ["onboarding"]
      }
    ],
    "count": 15,
    "queryTimeMs": 12
  }
}

POST/memory/context

Get Context

Build a formatted context block for AI system prompts. Returns a string ready to inject into your AI's context window.

Scope: read

Request Body

Parameter	Type	Required	Description
userId	`string`	Optional	User ID to get context for.
tenantId	`string`	Optional	Tenant organization ID.
maxTokens	`number`	Optional	Maximum tokens for the context (100-8000).Default: 2000
focus	`string[]`	Optional	Domains to prioritize in context.
includeRecent	`boolean`	Optional	Include recent activity.Default: true
orgWide	`boolean`	Optional	Include org-wide context (admin only).Default: false

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/context \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "maxTokens": 1500,
    "focus": ["work", "projects"],
    "includeRecent": true
  }'

Response

{
  "success": true,
  "data": {
    "context": "# User Context\n\n## Identity\n- Name: Alex\n- Role: Software Engineer\n\n## Preferences\n- Prefers dark mode\n- Uses TypeScript\n\n## Recent Activity\n- Working on API documentation\n- Completed onboarding tutorial",
    "memoryCount": 12,
    "estimatedTokens": 156,
    "memoriesUsed": ["mem_abc123", "mem_def456"]
  }
}

POST/memory/extract

Extract (Preview)

Extract memories from content without storing them. Useful for previewing what would be extracted before ingesting.

Scope: read

Request Body

Parameter	Type	Required	Description
source	`object`	Required	Source info: type (conversation, document, text) and optional context.
messages	`Message[]`	Optional	For conversation type: array of messages.
document	`object`	Optional	For document type: text, title, type.
text	`string`	Optional	For text type: raw text content.
tenantId	`string`	Optional	Tenant organization ID.

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/extract \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "text" },
    "text": "I work at Acme Corp as a senior engineer. My manager is Sarah and we have standups every Monday at 9am."
  }'

Response

{
  "success": true,
  "data": {
    "memories": [
      {
        "content": "User works at Acme Corp as a senior engineer.",
        "ring": "semantic",
        "domain": "work",
        "category": "identity",
        "importance": 8,
        "confidence": 0.95,
        "tags": ["work", "acme-corp", "engineer"]
      },
      {
        "content": "User's manager is Sarah.",
        "ring": "semantic",
        "domain": "work",
        "category": "relationship_fact",
        "importance": 6,
        "confidence": 0.9,
        "tags": ["work", "manager"]
      }
    ],
    "tasks": [],
    "stats": {
      "inputTokens": 45,
      "outputTokens": 156,
      "processingTimeMs": 312
    }
  }
}

GET/memory/stats

Usage Statistics

Get usage statistics for your organization including memory counts, query usage, and limits.

Scope: read

Query Parameters

Parameter	Type	Required	Description
tenantId	`string`	Optional	Get stats for a specific tenant.

Example Request

curl https://memory.hypersparkai.com//api/v1/memory/stats \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "organization": {
      "id": "org_abc123",
      "name": "My Company",
      "plan": "personal"
    },
    "limits": {
      "memories": 10000,
      "monthlyQueries": 5000
    },
    "usage": {
      "memories": 1234,
      "monthlyQueries": 567,
      "uniqueUsers": 3
    },
    "operations": {
      "ingest": 45,
      "recall": 320,
      "context": 150,
      "extract": 52
    },
    "tokens": 125000,
    "period": {
      "start": "2025-01-01T00:00:00.000Z",
      "end": "2025-01-15T12:00:00.000Z"
    }
  }
}

POST/memory/forget/preview

Forget Preview

Generate a forget plan with AI adjudication. The AI decides whether each memory should be FORGET, KEEP, or REWRITE based on your request.

Scope: delete

Two-Step Process

Forgetting is a two-step process: first preview, then confirm. This prevents accidental data loss.

Request Body

Parameter	Type	Required	Description
query	`string`	Required	Natural language description of what to forget (e.g., 'my old address').
userId	`string`	Optional	User ID to scope the search.
tenantId	`string`	Optional	Tenant organization ID.
topK	`number`	Optional	Maximum memories to consider.Default: 50
orgWide	`boolean`	Optional	Search across all users (admin only).Default: false

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/forget/preview \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "query": "my old home address"
  }'

Response

{
  "success": true,
  "data": {
    "planId": "550e8400-e29b-41d4-a716-446655440000",
    "summary": "Found 3 memories related to your old address. 2 will be deleted, 1 will be rewritten to remove only the address.",
    "willForget": [
      {
        "memoryId": "mem_abc123",
        "content": "User lives at 123 Main St, Springfield.",
        "reason": "Directly contains the old address."
      }
    ],
    "willRewrite": [
      {
        "memoryId": "mem_def456",
        "originalContent": "User moved from 123 Main St to Seattle for a new job.",
        "replacementContent": "User moved to Seattle for a new job.",
        "reason": "Contains address but also valuable job info."
      }
    ],
    "willKeep": [
      {
        "memoryId": "mem_ghi789",
        "content": "User prefers urban living.",
        "reason": "Not related to specific address."
      }
    ],
    "expiresAt": "2025-01-01T01:00:00.000Z",
    "memoriesSearched": 50
  }
}

POST/memory/forget/execute

Forget Execute

Execute a previously created forget plan. Requires explicit confirmation to prevent accidental deletion.

Scope: delete

Request Body

Parameter	Type	Required	Description
planId	`string (UUID)`	Required	The plan ID from the preview response.
confirm	`boolean`	Required	Must be true to execute. Safety check.
tenantId	`string`	Optional	Tenant organization ID.

Irreversible Action

Executing a forget plan permanently deletes or modifies memories. Plans expire after 1 hour.

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/forget/execute \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "550e8400-e29b-41d4-a716-446655440000",
    "confirm": true
  }'

Response

{
  "success": true,
  "data": {
    "planId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "executed",
    "forgotten": 2,
    "rewritten": 1,
    "kept": 1,
    "executedAt": "2025-01-01T00:30:00.000Z"
  }
}

GET/memory/graph

Graph Traversal

Explore connected memories using graph traversal. Returns nodes (memories) and edges (links) starting from a root memory.

Scope: read

Org-Level Only

Graph traversal operates at the organization level. It does not support tenantId scoping.

Query Parameters

Parameter	Type	Required	Description
memoryId	`string`	Required	The root memory ID to start traversal from.
maxHops	`number`	Optional	Maximum depth of traversal (1-5).Default: 2
minConfidence	`number`	Optional	Minimum link confidence threshold (0-1).Default: 0.6
linkTypes	`string`	Optional	Comma-separated list of link types to follow.
includeContent	`boolean`	Optional	Include full memory content for each node.Default: false

Link Types

Type	Description
created_from	Memory was created from another
supersedes	Memory replaces/updates another
contradicts	Memory conflicts with another
references	Memory mentions another
informed_by	Decision was informed by this memory
precedent_for	Decision sets precedent for another
same_entity	Memories share a common entity
topically_related	Memories share common topics
similar_to	Semantically similar memories

Example Request

curl "https://memory.hypersparkai.com//api/v1/memory/graph?memoryId=mem_abc123&maxHops=2&includeContent=true" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "rootMemoryId": "mem_abc123",
    "nodes": [
      {
        "memoryId": "mem_abc123",
        "depth": 0,
        "memory": {
          "content": "User approved the API design for v2.",
          "ring": "episodic",
          "domain": "work",
          "importance": 8,
          "isDecision": true,
          "decisionAction": "approved_api_design"
        }
      },
      {
        "memoryId": "mem_def456",
        "depth": 1,
        "memory": {
          "content": "API should use REST principles.",
          "ring": "semantic",
          "domain": "work",
          "importance": 6,
          "isDecision": false,
          "decisionAction": null
        }
      }
    ],
    "edges": [
      {
        "source": "mem_abc123",
        "target": "mem_def456",
        "linkType": "informed_by",
        "confidence": 0.95,
        "depth": 1
      }
    ],
    "stats": {
      "nodeCount": 2,
      "edgeCount": 1,
      "maxDepth": 1
    }
  }
}

GET/memory/links

Get Links

Get all links associated with a specific memory. Returns both outgoing and incoming links.

Scope: read

Org-Level Only

Links API operates at the organization level. It does not support tenantId scoping.

Query Parameters

Parameter	Type	Required	Description
memoryId	`string`	Required	The memory ID to get links for.
minConfidence	`number`	Optional	Minimum confidence threshold (0-1).
linkTypes	`string`	Optional	Comma-separated list of link types to include.

Example Request

curl "https://memory.hypersparkai.com//api/v1/memory/links?memoryId=mem_abc123&minConfidence=0.7" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "memoryId": "mem_abc123",
    "links": [
      {
        "id": "link_xyz789",
        "sourceMemoryId": "mem_abc123",
        "targetMemoryId": "mem_def456",
        "linkType": "informed_by",
        "isBidirectional": false,
        "confidence": 0.95,
        "confidenceTier": "high",
        "createdBy": "system",
        "sharedEntities": ["API", "design"],
        "createdAt": "2025-01-01T12:00:00.000Z"
      }
    ],
    "count": 1
  }
}

POST/memory/links

Create Link

Create an explicit link between two memories. Useful for manual relationship tracking.

Scope: write

Request Body

Parameter	Type	Required	Description
sourceMemoryId	`string`	Required	The source memory ID.
targetMemoryId	`string`	Required	The target memory ID.
linkType	`string`	Required	Type of link (see link types above).
isBidirectional	`boolean`	Optional	Create links in both directions.Default: false
userId	`string`	Optional	User ID for attribution.

Example Request

curl -X POST https://memory.hypersparkai.com//api/v1/memory/links \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceMemoryId": "mem_abc123",
    "targetMemoryId": "mem_def456",
    "linkType": "references",
    "isBidirectional": false
  }'

Response

{
  "success": true,
  "data": {
    "link": {
      "id": "link_xyz789",
      "sourceMemoryId": "mem_abc123",
      "targetMemoryId": "mem_def456",
      "linkType": "references",
      "confidence": 1.0,
      "createdAt": "2025-01-01T12:00:00.000Z"
    }
  }
}

DELETE/memory/links

Delete Link

Delete or invalidate a link between memories. Soft-delete by default (marks as invalid), hard-delete optional.

Scope: delete

Query Parameters

Parameter	Type	Required	Description
linkId	`string`	Required	The link ID to delete.
reason	`string`	Optional	Reason for invalidation (for audit trail).Default: User deleted
hardDelete	`boolean`	Optional	Permanently delete instead of soft-delete.Default: false

Example Request

curl -X DELETE "https://memory.hypersparkai.com//api/v1/memory/links?linkId=link_xyz789&reason=Incorrect%20relationship" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "linkId": "link_xyz789",
    "action": "invalidated"
  }
}

GET/memory/content

Get Content

Fetch the full content of a specific memory by ID. Retrieves complete memory data from storage.

Scope: read

Query Parameters

Parameter	Type	Required	Description
memoryId	`string`	Required	The memory ID to retrieve.
tenantId	`string`	Optional	Tenant organization ID for multi-tenant apps.

Example Request

curl "https://memory.hypersparkai.com//api/v1/memory/content?memoryId=mem_abc123" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "memoryId": "mem_abc123",
    "content": "User works at Acme Corp as a senior software engineer. They have been with the company for 3 years.",
    "ring": "semantic",
    "domain": "work",
    "category": "identity",
    "importance": 8,
    "confidence": 0.95,
    "tags": ["work", "acme-corp", "engineer"],
    "source": {
      "type": "conversation",
      "context": "onboarding chat"
    },
    "createdAt": "2025-01-01T12:00:00.000Z",
    "occurredAt": "2025-01-01T12:00:00.000Z"
  }
}

404 Response

Returns a 404 status with { success: false, error: 'Memory not found' } if the memory does not exist.

GET/memory/:memoryId/decisions

Decisions Reverse Lookup

Find all decisions that were informed by a specific memory. Enables reverse lineage queries to understand how a memory influenced decision-making.

Scope: read

Path Parameters

Parameter	Type	Required	Description
memoryId	`string`	Required	The memory ID to find related decisions for.

Query Parameters

Parameter	Type	Required	Description
outcome	`string`	Optional	Filter by decision outcome: pending, successful, failed.
limit	`number`	Optional	Maximum number of decisions to return.Default: 50

Example Request

curl "https://memory.hypersparkai.com//api/v1/memory/mem_abc123/decisions?outcome=successful&limit=10" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "memoryId": "mem_abc123",
    "totalDecisions": 2,
    "decisions": [
      {
        "memoryId": "mem_decision_xyz",
        "contentPreview": "Approved the new API design based on REST principles and team feedback.",
        "ring": "episodic",
        "domain": "work",
        "importance": 8,
        "decisionAction": "approved_api_design",
        "decisionOutcome": "successful",
        "isException": false,
        "isPrecedent": true,
        "policyApplied": "api_design_standards",
        "createdAt": "2025-01-02T14:30:00.000Z",
        "linkConfidence": 0.95,
        "linkedAt": "2025-01-02T14:30:00.000Z"
      },
      {
        "memoryId": "mem_decision_abc",
        "contentPreview": "Selected TypeScript for the project based on team expertise.",
        "ring": "episodic",
        "domain": "work",
        "importance": 7,
        "decisionAction": "selected_typescript",
        "decisionOutcome": "successful",
        "isException": false,
        "isPrecedent": false,
        "policyApplied": null,
        "createdAt": "2025-01-03T10:00:00.000Z",
        "linkConfidence": 0.88,
        "linkedAt": "2025-01-03T10:00:00.000Z"
      }
    ]
  }
}

Decision Intelligence

This endpoint is part of the Decision Intelligence system. Use it to trace which decisions were informed by specific memories, enabling full lineage tracking and audit trails.

Back to API Reference