Memory lifecycle

Memory is user-scoped at the database boundary. The public recall path still performs an ownership check after Cogix returns candidates, so a memory whose user_id does not match the requester is dropped before response serialization.

Write

POST /api/remember stores a memory for the current user. Valid memory types are semantic, episodic, procedural, and foundational.

For direct browsing and management, /api/memories exposes list, counts, timeline index, single-memory fetch, hybrid search, delete, bulk delete, wipe, pin, and pinned-list endpoints.

Deep remember

Both the API and MCP tools support a deeper path. In MCP, remember accepts mode: "auto" | "deep" | "shallow". The deep path searches related memories, classifies the input as duplicate, refinement, or new content, then writes or skips accordingly.

Use deep remember for durable facts and identity-like anchors. Use shallow remember for time-bound episodic notes where uniqueness is already supplied by the event timestamp.

Recall

POST /api/recall performs semantic recall and can be filtered by memory type. The route expands the fetch window, applies temporal inference, enforces user ownership, filters meta memories for lower tiers, then serializes memory IDs, text, type, age, creation time, similarity, and temporal context.

/api/memories/search combines full-text search with vector search and fuses ranked results. That endpoint is useful for UI browsing because it returns the same serialized memory shape as the list endpoint.

Correct and forget

Use update when a fact is stale but the topic is still useful. Use forget or memory deletion when a record should stop participating in recall. The MCP update tool corrects by ID and re-embeds the replacement text.

Foundational memories are pinned identity/context records. They are always more load-bearing than ordinary semantic notes, so keep them short, literal, and current.