API Reference

Decision Intelligence

Search for precedents, trace decision lineage, replay what was known at decision time, and analyze decision patterns. Build AI systems that learn from past decisions.

Find Precedents

Search similar past decisions

Decision Lineage

Trace what informed each decision

Decision Replay

Reconstruct point-in-time context

Analytics

Aggregate decision statistics

Decision Intelligence Workflow

Log decisions using the log_decision MCP tool or memory ingest API
Search for precedents before making similar decisions
Trace lineage to understand what informed past decisions
Update outcomes to improve future precedent searches

Base URL

$https://memory.hypersparkai.com//api/v1/memory

Org-Level Only

Decisions API operates at the organization level and does not support tenantId scoping. While userId is optional, some organization configurations may return a 400 error if userId cannot be inferred from the API key context.

POST/api/v1/memory/precedents

Find Precedents

Search for similar past decisions that can inform the current situation. Uses semantic similarity with decision-specific filters.

Request Body

Parameter	Type	Required	Description
query	string	Yes	Natural language description of the current situation
userId	string	No	Scope search to specific user
outcome	string	No	Filter by outcome: pending, successful, failed, unknown
isException	boolean	No	Only return policy exceptions
domain	string	No	Filter by life domain (work, finance, etc.)
minConfidence	number	No	Minimum similarity score (0-1)
includeChain	boolean	No	Include full precedent chain for each result
maxChainDepth	number	No	Max hops in precedent chain (1-5, default: 2)
topK	number	No	Number of results (1-50, default: 10)

Example Request

curl -X POST "https://memory.hypersparkai.com//api/v1/memory/precedents" \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Customer requesting refund after 60-day policy window",
    "outcome": "successful",
    "includeChain": true,
    "topK": 5
  }'

Response

{
  "success": true,
  "data": {
    "precedents": [
      {
        "decision": {
          "memoryId": "mem_abc123",
          "content": "Approved refund for long-term customer despite 60-day window...",
          "ring": "episodic",
          "domain": "work",
          "importance": 8,
          "isDecision": true,
          "decisionAction": "approved_refund",
          "decisionOutcome": "successful",
          "isException": true,
          "isPrecedent": true,
          "createdAt": "2024-06-15T10:30:00Z"
        },
        "similarity": 0.92,
        "decisionMetadata": {
          "action": "approved_refund",
          "rationale": "Customer loyalty outweighs policy adherence",
          "policyApplied": "refund_policy_v2",
          "exceptionType": "customer_loyalty"
        },
        "chain": [
          {
            "memoryId": "mem_xyz789",
            "content": "Customer has been with us for 5 years...",
            "linkType": "informed_by",
            "hopDistance": 1
          }
        ]
      }
    ],
    "totalFound": 3,
    "query": "Customer requesting refund after 60-day policy window"
  }
}

GET/api/v1/memory/lineage

Get Decision Lineage

Get the full context of a decision - what informed it and what resulted from it.

Query Parameters

Parameter	Type	Required	Description
memoryId	string	Yes	The memory ID of the decision to trace

Example Request

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

Response

{
  "success": true,
  "data": {
    "decision": {
      "memoryId": "mem_abc123",
      "content": "Approved 20% discount for enterprise renewal",
      "ring": "episodic",
      "domain": "work",
      "importance": 9,
      "isDecision": true,
      "decisionAction": "approved_discount",
      "decisionOutcome": "successful",
      "createdAt": "2024-12-01T14:30:00Z"
    },
    "informedBy": [
      {
        "memoryId": "mem_xyz001",
        "content": "Customer has 3-year history with zero support tickets",
        "linkType": "informed_by"
      },
      {
        "memoryId": "mem_xyz002",
        "content": "Retention discount policy allows up to 25%",
        "linkType": "informed_by"
      }
    ],
    "ledTo": [
      {
        "memoryId": "mem_xyz003",
        "content": "Customer renewed annual contract for $48,000",
        "linkType": "enabled"
      }
    ],
    "relatedEntities": ["Acme Corp", "Enterprise Plan", "John Smith"],
    "timeline": [
      {
        "memoryId": "mem_xyz001",
        "content": "Customer has 3-year history...",
        "relationship": "context",
        "date": "2024-11-15T10:00:00Z"
      },
      {
        "memoryId": "mem_abc123",
        "content": "Approved 20% discount...",
        "relationship": "decision",
        "date": "2024-12-01T14:30:00Z"
      },
      {
        "memoryId": "mem_xyz003",
        "content": "Customer renewed...",
        "relationship": "outcome",
        "date": "2024-12-05T09:15:00Z"
      }
    ]
  }
}

POST/api/v1/memory/lineage

Replay Decision

Reconstruct what was known at the moment a decision was made. See the context that existed then vs. what came after.

Request Body

Parameter	Type	Required	Description
memoryId	string	Yes	The memory ID of the decision to replay
userId	string	No	User ID for context scoping

Example Request

curl -X POST "https://memory.hypersparkai.com//api/v1/memory/lineage" \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "memoryId": "mem_abc123"
  }'

Response

{
  "success": true,
  "data": {
    "decision": {
      "memoryId": "mem_abc123",
      "content": "Approved 20% discount for enterprise renewal",
      "decisionAction": "approved_discount",
      "decisionOutcome": "successful"
    },
    "pointInTime": "2024-12-01T14:30:00Z",
    "memoriesAtTime": [
      {
        "memoryId": "mem_xyz001",
        "content": "Customer has 3-year history with zero support tickets",
        "ring": "semantic",
        "domain": "work",
        "createdAt": "2024-11-15T10:00:00Z"
      }
    ],
    "subsequentMemories": [
      {
        "memoryId": "mem_xyz003",
        "content": "Customer renewed annual contract for $48,000",
        "ring": "episodic",
        "domain": "work",
        "createdAt": "2024-12-05T09:15:00Z"
      }
    ],
    "outcome": {
      "status": "successful",
      "notes": "Customer renewed with 20% discount. Revenue retained: $48,000/year"
    }
  }
}

GET/api/v1/memory/decisions/stats

Decision Analytics

Get aggregate statistics about decisions including success rates, exception patterns, and policy usage.

Query Parameters

Parameter	Type	Description
userId	string	Filter stats to specific user
since	string	Time filter: 7d, 30d, 90d, or year

Example Request

curl -X GET "https://memory.hypersparkai.com//api/v1/memory/decisions/stats?since=30d" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "data": {
    "summary": {
      "totalDecisions": 156,
      "successRate": 0.78,
      "failureRate": 0.12,
      "exceptionRate": 0.15,
      "precedentRate": 0.08
    },
    "outcomes": {
      "successful": 122,
      "failed": 19,
      "pending": 12,
      "unknown": 3
    },
    "special": {
      "exceptions": 24,
      "precedents": 13
    },
    "revisits": {
      "overdue": 3,
      "upcomingWeek": 5
    },
    "topPoliciesApplied": [
      { "policy": "refund_policy_v2", "count": 45 },
      { "policy": "discount_guidelines", "count": 32 },
      { "policy": "escalation_matrix", "count": 21 }
    ],
    "topActions": [
      { "action": "approved_discount", "count": 52 },
      { "action": "approved_refund", "count": 34 },
      { "action": "escalated_to_manager", "count": 28 }
    ],
    "byDomain": {
      "work": 89,
      "finance": 42,
      "projects": 25
    },
    "filters": {
      "userId": "all",
      "since": "30d"
    }
  }
}

Decision Metadata Fields

Decisions stored via the log_decision MCP tool or memory ingest API include these fields:

Field	Type	Description
isDecision	boolean	True for all decision memories
decisionAction	string	Snake_case action identifier (e.g., approved_discount)
decisionOutcome	string	pending \| successful \| failed \| unknown
isException	boolean	True if this was a policy exception
isPrecedent	boolean	True if this decision sets precedent for future
policyApplied	string	Policy identifier that was applied
revisitAfter	string	ISO date when decision should be reviewed
revisitReason	string	Why this decision needs future review

Common Use Cases

Before Making a Decision

Search for precedents to ensure consistency with past decisions and learn from what worked.

// Find how similar situations were handled
await fetch('/api/v1/memory/precedents', {
  method: 'POST',
  body: JSON.stringify({
    query: 'Customer asking for deadline extension',
    outcome: 'successful'
  })
});

Auditing Past Decisions

Trace lineage to understand what information led to a decision.

// Get full decision context
await fetch(
  '/api/v1/memory/lineage?memoryId=mem_abc123'
);

Tenant Management API