Iblai api agent memory

iblai-api-agent-memory

Manage an agent's memories through the API: browse and filter what an agent has remembered, curate global (cross-agent) memories, add / edit / delete individual memories, manage the categories memories are filed under, and control capture / recall settings. Use when inspecting or curating what an agent remembers.

Auth & conventions

• Base URL: https://api.iblai.app
• Header: Authorization: Api-Token $IBLAI_API_KEY on every request.
• Path vars: {org} = $IBLAI_ORG, {username} = $IBLAI_USERNAME, {mentor} = the agent's unique id (e.g. d17dc729-60fd-4363-81a0-f67d9318b03e).
• Prefix / two spellings: endpoints live under the ai-mentor base https://api.iblai.app/dm/api/ai-mentor/orgs/{org} (the leading … below). A twin ai-agent base mirrors every route with the mentor path token swapped for agent (…/mentors/{mentor}/mentor-memories/ ↔ …/agents/{agent}/agent-memories/); either works.
• Two path bases: user-scoped routes hang off …/orgs/{org}/users/{username} (written {u} below); memory categories hang off …/orgs/{org}/mentors/{mentor} directly (no user segment).
• Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG, IBLAI_USERNAME, and IBLAI_API_KEY.

Concepts

Two PGVector-backed memory stores ("memsearch") sit behind these endpoints:

• Global memories (UserGlobalMemory) — scoped to a user + org, shared across every agent; facts any agent should know about the user.
• Agent (mentor) memories (UserMentorMemory) — scoped to a user + one agent + a category; what a single agent remembers about the user.

Categories (MentorMemoryCategory, per agent) file agent memories and steer capture: each has a slug, an extraction_prompt (LLM hint for what to pull into that category), and is_active (whether it's used during extraction).

Capture & injection are controlled per user via memsearch-settings:

• auto_capture_enabled — agents auto-extract memories from conversations. Auto-extracted rows carry is_auto_generated: true; memories you add via the API are false.
• use_memory_in_responses — stored memories are injected into agent responses.

An org-wide enable_memsearch flag gates the whole feature (see memsearch-status).

Reads

Agent (mentor) memories

• GET …/users/{username}/mentors/{mentor}/mentor-memories-list/?page={n}&page_size={n}&category={slug}&my_memory={bool}&user_id={id}&email={e}&start_date={yyyy-MM-dd}&end_date={yyyy-MM-dd} — paged flat list for one agent.
• GET …/users/{username}/mentors/{mentor}/mentor-memories/?my_memory={bool}&user_id={id}&email={e}&start_date=&end_date= — the same memories grouped by category.
• GET {u}/mentor-memories/?mentor={agent}&user_id={id}&email={e}&start_date=&end_date= — the user's agent memories across all agents; add ?mentor= to scope to one. Twin spelling: {u}/agent-memories/.

Categories

• GET …/orgs/{org}/mentors/{mentor}/memory-categories/ — category list for one agent.

Global (cross-agent) memories

• GET {u}/global-memories/?user_id={id}&email={e}&session_id={uuid}&content={substr}&start_date={yyyy-MM-dd}&end_date={yyyy-MM-dd} — user-level memories shared across every agent. Filters: session_id (the source session), content (case-insensitive substring), and the start_date / end_date created-at range.

Settings

• GET {u}/memsearch-settings/ — the user's capture / recall settings.
• GET {u}/memsearch-status/ — whether memsearch (enable_memsearch) is enabled for the org.

Writes

Agent (mentor) memories

• POST …/users/{username}/mentors/{mentor}/mentor-memories/ — add a memory:

  {
    "category_slug": "string (required, must match an existing category slug)",
    "content": "string (required, ≥10 chars)"
  }
  

• PATCH …/users/{username}/mentors/{mentor}/mentor-memories/{memoryId}/ — edit a memory (send at least one field):

  {
    "category_slug": "string",
    "content": "string (≥10 chars)"
  }
  

• DELETE …/users/{username}/mentors/{mentor}/mentor-memories/{memoryId}/ — delete one memory (no body). Destructive — confirm with the user first. Bulk delete = one call per memory.

Categories

• POST …/orgs/{org}/mentors/{mentor}/memory-categories/ — add a category:

  {
    "name": "string (required)",
    "slug": "string (required, unique per agent)",
    "description": "string",
    "extraction_prompt": "string",
    "is_active": "boolean (default true)"
  }
  

• PATCH …/orgs/{org}/mentors/{mentor}/memory-categories/{categoryId}/ — edit a category (any subset of the create fields).
• DELETE …/orgs/{org}/mentors/{mentor}/memory-categories/{categoryId}/ — delete a category (no body). Destructive — confirm with the user first.

Global (cross-agent) memories

• POST {u}/global-memories/ — add a user-level memory: { "content": "string (required, ≥10 chars)" }.
• DELETE {u}/global-memories/{memoryId}/ — delete one (no body). Destructive — confirm with the user first.

Settings

• PUT {u}/memsearch-settings/ — update the user's capture / recall settings (send at least one field):

  {
    "auto_capture_enabled": "boolean",
    "use_memory_in_responses": "boolean"
  }
  

Example

List the first page of one agent's memories filed under the preferences category since the start of the year:

curl -s \
  "https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/$MENTOR/mentor-memories-list/?page=1&page_size=20&category=preferences&start_date=2026-01-01" \
  -H "Authorization: Api-Token $IBLAI_API_KEY"

Notes

• Memories are filed under categories; category_slug on an agent memory must match an existing category's slug from the memory-categories/ endpoint.
• The mentor-memories-list/ filters stack — combine category, user_id, email, and the date range to narrow results; my_memory=true scopes the list to the caller's own memories.
• Global memories filter by user_id / email plus session_id, content (substring), and a start_date / end_date range — but not category or my_memory, which are agent-memory-only (global memories aren't categorized).
• Categories are org- + agent-scoped (…/orgs/{org}/mentors/{mentor}/…), not user-scoped like the memory endpoints.
• There is no bulk-delete endpoint: to clear several memories, issue one DELETE per id.
• Flat list reads (global memories, agent/mentor memories, categories) return a DRF page envelope — { "count": n, "results": [...] }; iterate results. The grouped mentor-memories/ read instead buckets memories by category (see Reads). DELETEs return 204.

Schema

Memory object (every memory read returns this; UserMentorMemory / UserGlobalMemory):

field	mode	notes
id	ro	integer
content	req (write)	the memory text; ≥10 chars
username, email	ro	resolved from the user
mentor_id	ro	agent memories only
platform	ro	global memories only (org key)
category	ro	agent memories only; nested category object
source_session_id	ro	session the memory was extracted from, or null
is_auto_generated	ro	true = LLM-extracted, false = added via API
created_at, updated_at	ro	ISO 8601

Category object (MentorMemoryCategory): id (ro), name, slug (unique per agent), description, extraction_prompt, is_active (default true), created_at (ro).

Settings (memsearch-settings): auto_capture_enabled, use_memory_in_responses (both boolean, default true), updated_at (ro).

Reference material

Background that complements the endpoints above (not required to call the API):

• references/concepts.md — how extraction and injection actually behave (background capture, single-LLM-call, 3-layer dedup, top-5 semantic recall), the default categories, the org → agent → user enablement cascade, embedding/dedup specs, and a symptom→fix table.