5.2.1 Inputs ¶

text

Required string. The fact to remember. Up to MAX_TEXT_CHARS characters (default 16000). Texts shaped like secrets (API keys, JWTs, PEM private-key markers) are rejected with SECRET_REJECTED.

tags

Array of strings. Optional. Normalized to lowercase canonical forms (see Tag normalization).

source_provider

String. Optional. Name of the LLM or client that produced this memory. Useful for auditing.

importance

Number, 0–1. Optional, default 0.5. Reserved for future ranking work; currently stored but not used in recall scoring.

capture_mode

String. Optional. Either "explicit" (user explicitly asked to remember) or "inferred" (LLM decided on its own). Recorded as provenance.

session_id

String. Optional. Opaque conversation identifier. Stored as-is.

dedup_policy

String. Optional. One of "insert" (skip the semantic-dedup check), "skip_if_near" (return the existing id if a near-duplicate is found), or "ask" (default: insert anyway, but include the near-duplicates in the response).

expires_at

ISO 8601 timestamp. Optional. Recall excludes this memory after the date passes. Useful for time-limited facts.

last_confirmed_at

ISO 8601 timestamp. Optional. When this fact was last verified as still true. Defaults to now() on insert.

5.2.2 Output ¶

{
  "ok": true,
  "memory_id": 123,
  "message": "Ok",
  "near_duplicates": [...],         // present if dedup_policy = "ask"
  "previously_corrected": [...]     // present if any tombstones nearby
}

If the request was rejected for being a near-duplicate (dedup_policy = "skip_if_near"), the existing memory’s id is returned:

{
  "ok": true,
  "memory_id": 99,
  "message": "Already remembered",
  "near_duplicates": [...]
}

5.2.3 Errors ¶

INVALID_INPUT, SECRET_REJECTED, EMBEDDING_ERROR, DATABASE_ERROR.

5.2.4 Example ¶

{
  "name": "remember",
  "arguments": {
    "text": "My son Colby lives in Los Angeles.",
    "tags": ["family"],
    "capture_mode": "explicit"
  }
}