Memory Deep Dive

​

Authentication & roles

• All endpoints use bearer authentication with API keys from Dashboard → API Keys.
• Contributor keys can write and recall memories.
• Manager keys are required for /api/Memory/delete and /api/Memory/export.

Authorization: Bearer YOUR_API_KEY

​

Writing memories

{
  "userId": "resident-991",
  "projectId": "project_abc",
  "content": "Taylor Brooks prefers evening communications via email.",
  "tags": ["communications", "preferences"],
  "metadata": {
    "capturedBy": "rpa-bot",
    "origin": "post-visit-form"
  },
  "consentFlag": true
}

​

Tuning recall queries

• Body fields (schema MemoryRecallRequest):
  • userId (required)
  • projectId (required when scope is project or team)
  • scope — use user, project, or team
  • query — natural language search phrase (use * wildcard to fetch everything)
  • tags — optional array to narrow the search
• Query parameters:
  • summarized — include generated summary per memory (defaults to false)
  • reRank — apply an LLM reranker when many records match
  • type — choose between facts (default) and raw
  • similarityThreshold — float between 0 and 1; increase to narrow results
  • limit — number of memories to return (default 10)

curl "https://app.recallio.ai/api/Memory/recall?limit=8&similarityThreshold=0.4" \
  -H "Authorization: Bearer $RECALLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "resident-991",
    "projectId": "project_abc",
    "scope": "user",
    "query": "maintenance preferences",
    "tags": ["maintenance"]
  }'

​

Summaries and topic discovery

• /api/Memory/recall-summary provides an aggregated narrative of all memories that match the scope and tags. Use it to populate agent briefing cards.
• /api/Memory/recall-topics surfaces the taxonomy Recallio derived from the same dataset, grouped by topic and subtopic.

​

Administrative operations

​

Delete memories

• Body schema MemoryDeleteRequest requires scope (one of user, project, team).
• Provide userId and/or projectId depending on the scope.
• Requires a Manager key.

​

Export memories

​

Error handling

• 400 Bad Request — malformed body, missing required fields, or payload size limits. Inspect the ErrorReturnClass response for details.
• 401 Unauthorized — bearer token missing, expired, or lacking the necessary role.
• 403 Forbidden — attempting admin endpoints with a non-Manager key.
• 5xx — transient server error; retry with exponential backoff.

​

Best practices

• Normalize identifiers — consistently prefix userId (resident-, agent-) to make deletions and exports predictable.
• Tag thoughtfully — tags power both filtering and topic extraction; align on a shared taxonomy.
• Capture metadata — store source systems, timestamps, or consent references in metadata for audits.
• Use thresholds — start with similarityThreshold at 0.3 and adjust upward for precision-critical experiences.
• Automate lifecycle — schedule exports and run scoped deletions when residents churn.