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 $IBLAIAPIKEY on every request.
• Path vars: {org} = $IBLAIORG, {username} = $IBLAIUSERNAME,

{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,

IBLAIUSERNAME, and IBLAIAPI_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.

• Agent knowledge (MentorMemory) — scoped to one agent (org + mentor), not any

user and not categorized. Manually curated (never auto-extracted), it is injected into every user's chat with that agent as an ## Agent Knowledge block, gated by the agent's enablememorycomponent and each user's usememoryin_responses. This is shared "how the agent should behave / what it should always know" content, distinct from the per-user stores above.

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

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

• autocaptureenabled — agents auto-extract memories from conversations. Auto-extracted

rows carry isautogenerated: true; memories you add via the API are false.

• usememoryin_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}&pagesize={n}&category={slug}&mymemory={bool}&userid={id}&email={e}&startdate={yyyy-MM-dd}&end_date={yyyy-MM-dd} — paged flat list for one agent.
• GET …/users/{username}/mentors/{mentor}/mentor-memories/?mymemory={bool}&userid={id}&email={e}&startdate=&enddate= — the same memories grouped by category.
• GET {u}/mentor-memories/?mentor={agent}&userid={id}&email={e}&startdate=&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.

Agent knowledge (shared)

• GET …/orgs/{org}/mentors/{mentor}/agent-memories/?page={n}&pagesize={n} — paged list of the agent's shared knowledge entries (DRF page envelope; pagesize default 20, max 100). This path has no users/{username} segment — do not confuse it with the user-scoped {u}/agent-memories/ twin spelling above, which lists one user's per-agent memories.

Global (cross-agent) memories

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

Settings

• GET {u}/memsearch-settings/ — the user's capture / recall settings. Tenant admins may read another user's settings by putting that user's username in the {username} path segment; non-admins are restricted to their own (any other {username} resolves back to the caller).
• 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:

``json { "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):

``json { "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:

``json { "name": "string (required)", "slug": "string (required, unique per agent)", "description": "string", "extractionprompt": "string", "isactive": "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.

Agent knowledge (shared)

• POST …/orgs/{org}/mentors/{mentor}/agent-memories/ — add a shared knowledge entry:

``json { "content": "string (required, ≥10 chars)" } ` Dedups on a content hash: an identical entry returns 409 ({"error": "Memory already exists"}) rather than a duplicate; a new one returns 201` with the created object.

• PATCH …/orgs/{org}/mentors/{mentor}/agent-memories/{memoryId}/ — replace an entry's content:

``json { "content": "string (required, ≥10 chars)" } ` If the new content collides with another of the agent's entries, returns 409`.

• DELETE …/orgs/{org}/mentors/{mentor}/agent-memories/{memoryId}/ — delete one entry (no body, 204). 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). Tenant admins may update another user's settings by putting that user's username in the {username} path segment; non-admins are restricted to their own (any other {username} resolves back to the caller):

``json { "autocaptureenabled": "boolean", "usememoryin_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 userid / email plus sessionid, content (substring),

and a startdate / enddate 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.

• Two things share the agent-memories name. The user-scoped {u}/agent-memories/ (under

…/users/{username}) is the twin spelling of one user's per-agent memories; the org+agent-scoped …/orgs/{org}/mentors/{mentor}/agent-memories/ (no user segment) is the shared agent knowledge store. Different data, different path — pick by whether a users/{username} segment is present.

• 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):

Agent-knowledge object (MentorMemory; returned by the shared agent-memories endpoints):

No category, isautogenerated, or user fields — agent knowledge is shared and manually curated.

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

Settings (memsearch-settings): autocaptureenabled, usememoryinresponses (both boolean, default true), updatedat (ro).

Reference material

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

• [references/concepts.md](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.