Memory Triggers

Triggers are conditional automation rules that execute actions when memory events match specified conditions. Use triggers to send alerts, log events, or notify external services when specific patterns occur in your memory system.

Create Trigger

Create a new trigger with conditions and actions.

POST /v1/triggers

Request Body

Condition Types

Action Types

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/triggers \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-importance security alerts",
    "description": "Alert when high-importance security memories are stored",
    "conditions": [
      {
        "type": "AND_GROUP",
        "conditions": [
          {
            "type": "CATEGORY_EQUALS",
            "value": "security"
          },
          {
            "type": "IMPORTANCE_GTE",
            "value": 0.9
          }
        ]
      }
    ],
    "actions": [
      {
        "type": "SLACK_NOTIFICATION",
        "channel": "#security-alerts",
        "message_template": "High-importance security memory stored: {{memory.content}}"
      },
      {
        "type": "EMAIL_ALERT",
        "to": "[email protected]",
        "subject": "Engram: High-importance security memory"
      }
    ],
    "max_triggers_per_hour": 50,
    "max_triggers_per_day": 500
  }'

Python

from engrammemory import Engram

client = Engram(api_key="pr_live_xxxxx")

trigger = client.triggers.create(
    name="High-importance security alerts",
    description="Alert when high-importance security memories are stored",
    conditions=[
        {
            "type": "AND_GROUP",
            "conditions": [
                {"type": "CATEGORY_EQUALS", "value": "security"},
                {"type": "IMPORTANCE_GTE", "value": 0.9},
            ],
        }
    ],
    actions=[
        {
            "type": "SLACK_NOTIFICATION",
            "channel": "#security-alerts",
            "message_template": "High-importance security memory stored: {{memory.content}}",
        },
        {
            "type": "EMAIL_ALERT",
            "to": "[email protected]",
            "subject": "Engram: High-importance security memory",
        },
    ],
    max_triggers_per_hour=50,
    max_triggers_per_day=500,
)
print(f"Trigger created: {trigger.id}")

JavaScript

import { Engram } from "engrammemory-ai";

const client = new Engram({ apiKey: "pr_live_xxxxx" });

const trigger = await client.triggers.create({
  name: "High-importance security alerts",
  description: "Alert when high-importance security memories are stored",
  conditions: [
    {
      type: "AND_GROUP",
      conditions: [
        { type: "CATEGORY_EQUALS", value: "security" },
        { type: "IMPORTANCE_GTE", value: 0.9 },
      ],
    },
  ],
  actions: [
    {
      type: "SLACK_NOTIFICATION",
      channel: "#security-alerts",
      messageTemplate: "High-importance security memory stored: {{memory.content}}",
    },
    {
      type: "EMAIL_ALERT",
      to: "[email protected]",
      subject: "Engram: High-importance security memory",
    },
  ],
  maxTriggersPerHour: 50,
  maxTriggersPerDay: 500,
});
console.log(`Trigger created: ${trigger.id}`);

Response

{
  "id": "trg_abc123",
  "name": "High-importance security alerts",
  "description": "Alert when high-importance security memories are stored",
  "enabled": true,
  "conditions": [
    {
      "type": "AND_GROUP",
      "conditions": [
        { "type": "CATEGORY_EQUALS", "value": "security" },
        { "type": "IMPORTANCE_GTE", "value": 0.9 }
      ]
    }
  ],
  "actions": [
    {
      "type": "SLACK_NOTIFICATION",
      "channel": "#security-alerts",
      "message_template": "High-importance security memory stored: {{memory.content}}"
    },
    {
      "type": "EMAIL_ALERT",
      "to": "[email protected]",
      "subject": "Engram: High-importance security memory"
    }
  ],
  "max_triggers_per_hour": 50,
  "max_triggers_per_day": 500,
  "triggers_this_hour": 0,
  "triggers_today": 0,
  "created_at": "2026-04-10T12:00:00Z"
}

---

List Triggers

List all triggers for your account.

GET /v1/triggers

Query Parameters

Code Examples

cURL

curl "https://api.engrammemory.ai/v1/triggers?enabled=true" \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

triggers = client.triggers.list(enabled=True)
for t in triggers.items:
    print(f"{t.name}: {t.triggers_today} fires today")

JavaScript

const triggers = await client.triggers.list({ enabled: true });
triggers.items.forEach((t) => {
  console.log(`${t.name}: ${t.triggersToday} fires today`);
});

Response

{
  "items": [
    {
      "id": "trg_abc123",
      "name": "High-importance security alerts",
      "enabled": true,
      "conditions_count": 2,
      "actions_count": 2,
      "triggers_this_hour": 3,
      "triggers_today": 18,
      "last_triggered_at": "2026-04-10T14:20:00Z",
      "created_at": "2026-04-10T12:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}

---

Update Trigger

Update an existing trigger.

PATCH /v1/triggers/{trigger_id}

Path Parameters

Request Body

All fields are optional. Only include fields you want to update.

Code Examples

cURL

curl -X PATCH https://api.engrammemory.ai/v1/triggers/trg_abc123 \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "max_triggers_per_hour": 200,
    "enabled": false
  }'

Python

trigger = client.triggers.update(
    "trg_abc123",
    max_triggers_per_hour=200,
    enabled=False,
)

JavaScript

const trigger = await client.triggers.update("trg_abc123", {
  maxTriggersPerHour: 200,
  enabled: false,
});

Response

Returns the updated trigger object.

---

Delete Trigger

Permanently delete a trigger.

DELETE /v1/triggers/{trigger_id}

Path Parameters

Code Examples

cURL

curl -X DELETE https://api.engrammemory.ai/v1/triggers/trg_abc123 \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

client.triggers.delete("trg_abc123")

JavaScript

await client.triggers.delete("trg_abc123");

Response

204 No Content

---

Test Trigger

Test a trigger by sending a simulated memory event through the condition engine. Actions are executed in test mode (e.g., test webhook sends are flagged).

POST /v1/triggers/{trigger_id}/test

Path Parameters

Request Body (Optional)

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/triggers/trg_abc123/test \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "memory": {
      "content": "Critical security vulnerability detected in auth module",
      "metadata": {
        "category": "security",
        "importance": 0.95
      }
    }
  }'

Python

result = client.triggers.test(
    "trg_abc123",
    memory={
        "content": "Critical security vulnerability detected in auth module",
        "metadata": {"category": "security", "importance": 0.95},
    },
)
print(f"Matched: {result.conditions_matched}")
for action in result.actions_executed:
    print(f"  {action.type}: {action.status}")

JavaScript

const result = await client.triggers.test("trg_abc123", {
  memory: {
    content: "Critical security vulnerability detected in auth module",
    metadata: { category: "security", importance: 0.95 },
  },
});
console.log(`Matched: ${result.conditionsMatched}`);
result.actionsExecuted.forEach((action) => {
  console.log(`  ${action.type}: ${action.status}`);
});

Response

{
  "conditions_matched": true,
  "conditions_detail": [
    { "type": "CATEGORY_EQUALS", "value": "security", "matched": true },
    { "type": "IMPORTANCE_GTE", "value": 0.9, "matched": true }
  ],
  "actions_executed": [
    {
      "type": "SLACK_NOTIFICATION",
      "status": "SUCCESS",
      "response_time_ms": 230
    },
    {
      "type": "EMAIL_ALERT",
      "status": "SUCCESS",
      "response_time_ms": 1200
    }
  ],
  "test_mode": true
}

---

Trigger Analytics

Get execution statistics for a specific trigger.

GET /v1/triggers/{trigger_id}/analytics

Path Parameters

Code Examples

cURL

curl https://api.engrammemory.ai/v1/triggers/trg_abc123/analytics \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

analytics = client.triggers.analytics("trg_abc123")
print(f"Total executions: {analytics.total_executions}")
print(f"Success rate: {analytics.success_rate_pct}%")

JavaScript

const analytics = await client.triggers.analytics("trg_abc123");
console.log(`Total executions: ${analytics.totalExecutions}`);
console.log(`Success rate: ${analytics.successRatePct}%`);

Response

{
  "trigger_id": "trg_abc123",
  "total_executions": 1842,
  "successful_executions": 1820,
  "failed_executions": 22,
  "success_rate_pct": 98.81,
  "rate_limited_count": 5,
  "avg_evaluation_time_ms": 8,
  "actions_breakdown": {
    "SLACK_NOTIFICATION": { "total": 1842, "succeeded": 1830, "failed": 12 },
    "EMAIL_ALERT": { "total": 1842, "succeeded": 1832, "failed": 10 }
  },
  "hourly_distribution": {
    "00": 12, "01": 8, "02": 5, "08": 120, "09": 180,
    "10": 210, "14": 195, "15": 170, "16": 140
  },
  "period": "last_30_days"
}

---

Execution History

Get the execution history for a specific trigger.

GET /v1/triggers/{trigger_id}/executions

Path Parameters

Query Parameters

Code Examples

cURL

curl "https://api.engrammemory.ai/v1/triggers/trg_abc123/executions?page=1&status=FAILED" \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

executions = client.triggers.executions("trg_abc123", status="FAILED", page=1)
for ex in executions.items:
    print(f"{ex.id}: {ex.status} at {ex.executed_at}")
    for action in ex.action_results:
        print(f"  {action.type}: {action.error}")

JavaScript

const executions = await client.triggers.executions("trg_abc123", {
  status: "FAILED",
  page: 1,
});
executions.items.forEach((ex) => {
  console.log(`${ex.id}: ${ex.status} at ${ex.executedAt}`);
  ex.actionResults.forEach((action) => {
    console.log(`  ${action.type}: ${action.error}`);
  });
});

Response

{
  "items": [
    {
      "id": "exec_abc123",
      "trigger_id": "trg_abc123",
      "status": "SUCCESS",
      "memory_id": "mem_xyz789",
      "conditions_evaluated": 2,
      "conditions_matched": 2,
      "evaluation_time_ms": 6,
      "action_results": [
        {
          "type": "SLACK_NOTIFICATION",
          "status": "SUCCESS",
          "response_time_ms": 210
        },
        {
          "type": "EMAIL_ALERT",
          "status": "SUCCESS",
          "response_time_ms": 1100
        }
      ],
      "executed_at": "2026-04-10T14:30:00Z"
    },
    {
      "id": "exec_def456",
      "trigger_id": "trg_abc123",
      "status": "FAILED",
      "memory_id": "mem_abc456",
      "conditions_evaluated": 2,
      "conditions_matched": 2,
      "evaluation_time_ms": 5,
      "action_results": [
        {
          "type": "SLACK_NOTIFICATION",
          "status": "FAILED",
          "error": "Slack API returned 403: channel_not_found",
          "response_time_ms": 340
        },
        {
          "type": "EMAIL_ALERT",
          "status": "SUCCESS",
          "response_time_ms": 980
        }
      ],
      "executed_at": "2026-04-10T13:15:00Z"
    }
  ],
  "total": 22,
  "page": 1,
  "page_size": 20,
  "total_pages": 2
}

---

Template Variables

Action message templates support the following variables:

---

Error Codes