core/docs/ICD/memory.md

Memory

Long-term memory extracted from conversations. The system identifies facts, preferences, and context about the user and stores them for injection into future conversations.

Auth: All user endpoints require authenticated session. Admin endpoints require platform admin role.

---

User Memory

GET    /memories                    → { "data": [memory objects] }
GET    /memories/count              → { "active": 5, "pending": 2 }
PUT    /memories/:id                ← { "key": "...", "value": "...", "confidence": 0.9 }
DELETE /memories/:id
POST   /memories/:id/approve        → approve a pending_review memory
POST   /memories/:id/reject         → reject (archive) a pending_review memory

Query params for GET /memories:

Param	Default	Description
status	active	Filter by status: active, pending_review, archived
query	—	Keyword filter on key+value (PG: full-text, SQLite: LIKE)

Memory object:

{
  "id": "uuid",
  "scope": "user|persona|persona_user",
  "owner_id": "uuid",
  "user_id": "uuid|null",
  "key": "preferred language",
  "value": "Go with Gin framework for backend services",
  "source_channel_id": "uuid|null",
  "confidence": 0.85,
  "status": "active|pending_review|archived",
  "created_at": "...",
  "updated_at": "..."
}

Scopes:

Scope	owner_id	user_id	Description
user	user's ID	null	Personal facts, persist across all conversations
persona	persona's ID	null	Shared across all users of a Persona
persona_user	persona's ID	user's ID	Per-user facts within a Persona context

Ownership: PUT and DELETE enforce ownership — a user can only modify their own user-scope memories (owner_id == user_id).

Admin Memory Review

GET  /admin/memories/pending        → { "data": [memory objects] }
POST /admin/memories/bulk-approve   ← { "ids": ["uuid1", "uuid2"] }
                                    → { "approved": 2 }

Platform admin can review and bulk-approve pending memories across all users.

AI Tools (non-REST)

Two tools are registered for AI use during completions:

Tool	Description
memory_save	Save a fact with key, value, confidence. Saves as active (bypasses review).
memory_recall	Search memories by query. Uses hybrid semantic+keyword recall when embedder is configured.

Background Extraction

A background scanner periodically finds conversations with enough new activity and calls the utility model to extract memorable facts. Extracted memories are saved as pending_review.

Controlled by memory_extraction_enabled global config key and per-persona memory_enabled flag.

Memory Injection

Active memories are injected into the system prompt at completion time via BuildMemoryHint. Uses hybrid semantic recall when an embedder is available, falling back to keyword/confidence ranking. Budget: ~6000 characters.

---