SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsiblai-api-agent-memory

iblai-api-agent-memory

Coding & development

View repository

Updated 10-15 22:16

About this skill

iblai-api-agent-memory

★ Core family. With a screen: /iblai-vibe-memory-guide mounts the memory surfaces — org-wide admin, one agent's tab, the member's own view — this skill is the headless twin (same data, exact endpoints).

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 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 + agent), 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 enable_memory_component and each user's use_memory_in_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 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 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.

Agent knowledge (shared)

  • GET …/orgs/{org}/mentors/{mentor}/agent-memories/?page={n}&page_size={n} — paged list of the agent's shared knowledge entries (DRF page envelope; page_size 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/?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. Organization 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 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.

Agent knowledge (shared)

  • POST …/orgs/{org}/mentors/{mentor}/agent-memories/ — add a shared knowledge entry: 
    { "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: 
    { "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). Organization 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): 
    {
  "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.
  • 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 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, user_full_name ro resolved from the user; user_full_name is the display name, empty when the user has none
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

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

field mode notes
id ro integer
mentor_id ro the agent's unique id
mentor_name ro the agent's name
content req (write) the knowledge text; ≥10 chars
created_by ro username of the curator, or null (service/API-key callers)
created_by_email, created_by_full_name ro the curator's email and display name; both null when created_by is
created_at, updated_at ro ISO 8601

No category or is_auto_generated — agent knowledge is shared and manually curated, so the only user it names is the curator (created_by*), never a learner.

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.