/iblai-vibe-memory-guide
First time here? If iblai.env has no ARCHITECTURE=, run /iblai-vibe-start first (four questions; two minutes) — it decides single-org / multi-org / headless and who signs in, and every skill reads the answer.
Memory is the platform's answer to "make the app remember me". It is one data
model with three stores, three gates, and three ready-made surfaces. This page
tells you which to use; the linked skills mount them.
Common setup (brand, conventions, env files, verification): see docs/skill-setup.md.
1. Three stores
| Store |
Scope |
Written by |
Read by |
Typical content |
| Global memories |
one user, every agent in the org |
auto-capture from chats (auto badge) or the user by hand |
every agent the user talks to, when recall is on |
"Prefers concise answers", "Works in the finance team" |
| Agent memories |
one user × one agent, filed under categories |
auto-capture guided by each category's extraction prompt, or admins/the user by hand |
that agent only |
per the five default categories: knowledge_gaps, learning_goals, preferences, progress_milestones, personal_context |
| Agent knowledge |
one agent, no user — shared by everyone |
admins / the agent's owner, curated |
injected into every chat with that agent as ## Agent Knowledge |
"Our refund window is 30 days", "Always cite the policy handbook" |
Memories are short facts (≥ 10 characters). Auto-captured ones carry a robot
icon and an auto badge; manual ones a person icon.
2. Three gates (all must be open for memory to work)
| Level |
Flag |
Who sets it |
Where |
| Org |
enable_memsearch |
org admin (or ibl.ai operator) |
GET/POST …/users/{user_id}/memsearch-config/; read-only status …/memsearch-status/ |
| Agent |
enable_memory_component |
agent editor |
Agent Settings → Memory tab toggle (PUT …/mentors/{mentor}/settings/) |
| User |
auto_capture_enabled ("Allow AI to learn from our conversations"), use_memory_in_responses ("Use my saved information in responses") |
the user (admins may set another user's) |
Profile → Memory; GET/PUT …/users/{username}/memsearch-settings/ (defaults false) |
Visibility rule for your UI: hide memory management unless the org status
is enabled and the agent's flag is on — but always show the user's two
toggles so people can opt in or out. useGetMemsearchStatusQuery answers the
org gate from the browser.
3. Which surface for which audience
| Audience |
Wants |
Mount |
Skill |
| Member |
see/curate what is remembered about me; the two toggles |
Profile → targetTab="memory" (the Profile Memory tab) |
/iblai-vibe-profile |
| Agent owner / editor |
what this agent remembers about its users, by category; manage categories and extraction prompts; enable/disable |
AgentMemoryTab inside AgentSettingsProvider |
/iblai-vibe-agent-memory |
| Org admin / DPO / support |
any user's global memories and toggles; any agent's memories; corrections and deletions on someone's behalf |
Account → targetTab="memory" (Global + Agent tabs) |
/iblai-vibe-memory |
| Your own page ("what the app knows about you" card on the home page) |
list + add + delete global memories |
the hooks in §4 |
this page |
4. Building something custom
SDK hooks (@iblai/iblai-js/data-layer, verified 2.9.x):
| Hook |
Does |
useGetUserMemorySettingsQuery, useUpdateUserMemorySettingsMutation |
the user's two toggles |
useGetGlobalMemoriesQuery, useCreateGlobalMemoryMutation, useUpdateGlobalMemoryMutation, useDeleteGlobalMemoryMutation |
global memories |
useGetMentorMemoriesListQuery, useCreateMentorMemoryMutation |
agent memories (see get_api_query_info for the full set) |
useGetMemsearchStatusQuery, useGetMemsearchConfigQuery, useUpdateMemsearchConfigMutation |
the org gate |
Minimal "what the app remembers" card (member-facing):
"use client";
import {
useGetGlobalMemoriesQuery,
useDeleteGlobalMemoryMutation,
} from "@iblai/iblai-js/data-layer";
export function MemoryCard({ username }: { username: string }) {
const { data, isLoading } = useGetGlobalMemoriesQuery({ username, page: 1, page_size: 10 } as any);
const [remove] = useDeleteGlobalMemoryMutation();
if (isLoading) return null;
const items: any[] = (data as any)?.results ?? [];
return (
<ul className="space-y-2">
{items.map((m) => (
<li key={m.id} className="flex items-center justify-between rounded-md border p-2 text-sm">
<span>{m.content}</span>
<button className="text-xs text-red-600" => remove({ username, memory_id: m.id } as any)}>
Forget
</button>
</li>
))}
</ul>
);
}
Confirm the argument shapes with get_api_query_info("useGetGlobalMemoriesQuery")
before shipping — the .d.ts lags the runtime in places.
REST (server-side Api-Token, or the SDK's session token in the browser).
Prefix https://api.$DOMAIN/dm/api/ai-mentor/orgs/{org}/:
| Store |
Read |
Write |
| Agent memories |
GET users/{username}/mentors/{mentor}/mentor-memories-list/?page=&page_size=&category=&user_id=&start_date=&end_date= (flat) · …/mentor-memories/ (grouped by category) · users/{username}/mentor-memories/?mentor= (across agents) |
POST users/{username}/mentors/{mentor}/mentor-memories/ {category_slug, content} · PATCH …/{memoryId}/ · DELETE …/{memoryId}/ |
| Categories |
GET mentors/{mentor}/memory-categories/ |
POST (409 if slug exists) · PATCH …/{categoryId}/ (name, description, extraction prompt) · DELETE (soft) |
| Agent knowledge |
GET mentors/{mentor}/agent-memories/?page=&page_size= (no users/ segment) |
POST mentors/{mentor}/agent-memories/ · PATCH …/{memoryId}/ · DELETE …/{memoryId}/ (204) |
| Global memories |
GET users/{username}/global-memories/?user_id=&email=&session_id=&content=&start_date=&end_date= |
POST {content} (≥ 10 chars, 409 duplicate) · DELETE …/{memoryId}/ |
| Settings |
GET users/{username}/memsearch-settings/ · GET …/memsearch-status/ |
PUT users/{username}/memsearch-settings/ (admins may target another username) |
Errors: 400 content too short · 403 another user's memories without admin · 404 · 409 duplicate.
Full reference: iblai-api-agent-memory.
5. Privacy notes to tell the user
- Memory is personal data. Give members the two toggles and a way to delete (the Profile tab does both).
- Admin cross-user access exists for support and data-protection duties — gate your admin memory page on
isTenantAdmin() (see /iblai-vibe-admin).
- Agent knowledge is shared with everyone who talks to the agent; never put a person's data there.
Related skills
/iblai-vibe-profile — member's own Memory tab
/iblai-vibe-agent-memory — one agent's Memory tab
/iblai-vibe-memory — org-wide Memory admin
/iblai-vibe-agent-privacy — PII redaction/masking in chats (a different feature)
/iblai-vibe-api — calling endpoints that have no hook
1---2name: iblai-vibe-memory-guide3description: What memory means for an ibl.ai app and which surface to mount for which audience — user global memories, per-agent memories by category, shared agent knowledge, the org/agent/user gates that decide whether memory is on, and the SDK hooks and REST endpoints for anything custom. Use when the user mentions memory, remember, personalize, "what the agent knows about the user", forget, or wants memory UI in their app. For the org-wide admin surface see /iblai-vibe-memory; for one agent's tab see /iblai-vibe-agent-memory; the member's own view is the Profile Memory tab in /iblai-vibe-profile.4---56# /iblai-vibe-memory-guide78> **First time here?** If `iblai.env` has no `ARCHITECTURE=`, run `/iblai-vibe-start` first (four questions; two minutes) — it decides single-org / multi-org / headless and who signs in, and every skill reads the answer.910Memory is the platform's answer to "make the app remember me". It is one data11model with three stores, three gates, and three ready-made surfaces. This page12tells you which to use; the linked skills mount them.131415161718> **Common setup (brand, conventions, env files, verification):** see [docs/skill-setup.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/skill-setup.md).1920## 1. Three stores2122| Store | Scope | Written by | Read by | Typical content |23|---|---|---|---|---|24| **Global memories** | one user, **every** agent in the org | auto-capture from chats (`auto` badge) or the user by hand | every agent the user talks to, when recall is on | "Prefers concise answers", "Works in the finance team" |25| **Agent memories** | one user × **one agent**, filed under **categories** | auto-capture guided by each category's *extraction prompt*, or admins/the user by hand | that agent only | per the five default categories: `knowledge_gaps`, `learning_goals`, `preferences`, `progress_milestones`, `personal_context` |26| **Agent knowledge** | one agent, **no user** — shared by everyone | admins / the agent's owner, curated | injected into every chat with that agent as `## Agent Knowledge` | "Our refund window is 30 days", "Always cite the policy handbook" |2728Memories are short facts (≥ 10 characters). Auto-captured ones carry a robot29icon and an `auto` badge; manual ones a person icon.3031## 2. Three gates (all must be open for memory to work)3233| Level | Flag | Who sets it | Where |34|---|---|---|---|35| **Org** | `enable_memsearch` | org admin (or ibl.ai operator) | `GET/POST …/users/{user_id}/memsearch-config/`; read-only status `…/memsearch-status/` |36| **Agent** | `enable_memory_component` | agent editor | Agent Settings → Memory tab toggle (`PUT …/mentors/{mentor}/settings/`) |37| **User** | `auto_capture_enabled` ("Allow AI to learn from our conversations"), `use_memory_in_responses` ("Use my saved information in responses") | the user (admins may set another user's) | Profile → Memory; `GET/PUT …/users/{username}/memsearch-settings/` (defaults `false`) |3839**Visibility rule for your UI:** hide memory management unless the org status40is enabled **and** the agent's flag is on — but **always** show the user's two41toggles so people can opt in or out. `useGetMemsearchStatusQuery` answers the42org gate from the browser.4344## 3. Which surface for which audience4546| Audience | Wants | Mount | Skill |47|---|---|---|---|48| **Member** | see/curate what is remembered about *me*; the two toggles | `Profile` → `targetTab="memory"` (the Profile Memory tab) | `/iblai-vibe-profile` |49| **Agent owner / editor** | what *this agent* remembers about its users, by category; manage categories and extraction prompts; enable/disable | `AgentMemoryTab` inside `AgentSettingsProvider` | `/iblai-vibe-agent-memory` |50| **Org admin / DPO / support** | any user's global memories and toggles; any agent's memories; corrections and deletions on someone's behalf | `Account` → `targetTab="memory"` (Global + Agent tabs) | `/iblai-vibe-memory` |51| **Your own page** ("what the app knows about you" card on the home page) | list + add + delete global memories | the hooks in §4 | this page |5253## 4. Building something custom5455SDK hooks (`@iblai/iblai-js/data-layer`, verified 2.9.x):5657| Hook | Does |58|---|---|59| `useGetUserMemorySettingsQuery`, `useUpdateUserMemorySettingsMutation` | the user's two toggles |60| `useGetGlobalMemoriesQuery`, `useCreateGlobalMemoryMutation`, `useUpdateGlobalMemoryMutation`, `useDeleteGlobalMemoryMutation` | global memories |61| `useGetMentorMemoriesListQuery`, `useCreateMentorMemoryMutation` | agent memories (see `get_api_query_info` for the full set) |62| `useGetMemsearchStatusQuery`, `useGetMemsearchConfigQuery`, `useUpdateMemsearchConfigMutation` | the org gate |6364Minimal "what the app remembers" card (member-facing):6566```tsx67"use client";6869import {70 useGetGlobalMemoriesQuery,71 useDeleteGlobalMemoryMutation,72} from "@iblai/iblai-js/data-layer";7374export function MemoryCard({ username }: { username: string }) {75 const { data, isLoading } = useGetGlobalMemoriesQuery({ username, page: 1, page_size: 10 } as any);76 const [remove] = useDeleteGlobalMemoryMutation();77 if (isLoading) return null;78 const items: any[] = (data as any)?.results ?? [];79 return (80 <ul className="space-y-2">81 {items.map((m) => (82 <li key={m.id} className="flex items-center justify-between rounded-md border p-2 text-sm">83 <span>{m.content}</span>84 <button className="text-xs text-red-600" onClick={() => remove({ username, memory_id: m.id } as any)}>85 Forget86 </button>87 </li>88 ))}89 </ul>90 );91}92```9394Confirm the argument shapes with `get_api_query_info("useGetGlobalMemoriesQuery")`95before shipping — the `.d.ts` lags the runtime in places.9697REST (server-side `Api-Token`, or the SDK's session token in the browser).98Prefix `https://api.$DOMAIN/dm/api/ai-mentor/orgs/{org}/`:99100| Store | Read | Write |101|---|---|---|102| Agent memories | `GET users/{username}/mentors/{mentor}/mentor-memories-list/?page=&page_size=&category=&user_id=&start_date=&end_date=` (flat) · `…/mentor-memories/` (grouped by category) · `users/{username}/mentor-memories/?mentor=` (across agents) | `POST users/{username}/mentors/{mentor}/mentor-memories/` `{category_slug, content}` · `PATCH …/{memoryId}/` · `DELETE …/{memoryId}/` |103| Categories | `GET mentors/{mentor}/memory-categories/` | `POST` (409 if slug exists) · `PATCH …/{categoryId}/` (name, description, extraction prompt) · `DELETE` (soft) |104| Agent knowledge | `GET mentors/{mentor}/agent-memories/?page=&page_size=` (no `users/` segment) | `POST mentors/{mentor}/agent-memories/` · `PATCH …/{memoryId}/` · `DELETE …/{memoryId}/` (204) |105| Global memories | `GET users/{username}/global-memories/?user_id=&email=&session_id=&content=&start_date=&end_date=` | `POST` `{content}` (≥ 10 chars, 409 duplicate) · `DELETE …/{memoryId}/` |106| Settings | `GET users/{username}/memsearch-settings/` · `GET …/memsearch-status/` | `PUT users/{username}/memsearch-settings/` (admins may target another username) |107108Errors: `400` content too short · `403` another user's memories without admin · `404` · `409` duplicate.109Full reference: [iblai-api-agent-memory](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/skills/agents/iblai-api-agent-memory/SKILL.md).110111## 5. Privacy notes to tell the user112113- Memory is personal data. Give members the two toggles and a way to delete (the Profile tab does both).114- Admin cross-user access exists for support and data-protection duties — gate your admin memory page on `isTenantAdmin()` (see `/iblai-vibe-admin`).115- Agent knowledge is shared with everyone who talks to the agent; never put a person's data there.116117## Related skills118119- `/iblai-vibe-profile` — member's own Memory tab120- `/iblai-vibe-agent-memory` — one agent's Memory tab121- `/iblai-vibe-memory` — org-wide Memory admin122- `/iblai-vibe-agent-privacy` — PII redaction/masking in chats (a different feature)123- `/iblai-vibe-api` — calling endpoints that have no hook