Cortex memory is event-sourced where it matters and freshness-tracked throughout. It maps to a 6-type cognitive memory taxonomy (docs/design/10-work-p…
cortex-bootteam_events, messages, agent_sessionscortex-search (temporal)work_products, decisions, knowledgecortex-brief, vector searchlessons, rules, skillscortex-search, rule filescortex_entities/cortex_relationshipscortex-graph-*work_products.provenance, team_eventscortex-brief provenance trailwork_products (:1816)handoff_id, actor_id, activity_type (free-text convention, DEFAULT task-completed, slug-normalised; typical values implementation/review/migration/research/fix/content-published/asset-created/approval/campaign), status ∈ {current, stale, superseded}, files_changed[], symbols_changed[], subject_entities[], tests_run jsonb, risks[], followups[], commit_sha, content_hash, file_hashes, symbol_hashes, freshness_status, freshness_reason, projection_status, valid_from/valid_to, supersedes_id, embedding vector(768)decisions (:1590)summary, rationale, outcome, category, files_affected[], tags[], embedding, superseded_by, times_selected/applied/completed/fallback, quality_score, parent_decision_id, generation, actor_idlessons (:1717)knowledge (:1691)content, source_file, category, section, embedding, project-scoped (_global allowed)artifacts (:1406), artifact_edges (:1389)cortex_entities (:1555)cortex_relationships (:2109)retention_config (:2381) + archive_* tablestier2_days (default 90) drives hot→archive; archive_messages/events/decisions/lessons/handoffsagent_diaries (:1136)agent_name, summary, outcome, importance, search_vector, actor/project FKs; backs /diary/{agent}embedding_backfill_jobs (:2180)status ∈ {queued, running, completed, failed}| Action | Surface |
|---|---|
| Log decision/lesson/progress | cortex-log <agent> decision|lesson|progress → POST /log; bulk via /decisions/ingest, /lessons/ingest (conflict-detecting, on_conflict=conflict|update) |
| Record work product | cortex-work-product → POST /work-products |
| Retrieve brief | cortex-brief <file-or-symbol> |
| Check freshness | cortex-work-product --check-freshness --apply; cortex-maintain --freshness; Beat sweep |
| Backfill embeddings | cortex-embed → /beat/embeddings/backfill (pollable job) |
| Archive | retention worker moves hot→warm→archive_* |
immutable evidence event (handoff completed) → canonical WorkProduct record (write ONCE, projection_status=pending) → typed projections into L1–L6 (embedding, code graph, entity graph, boot briefs) → freshness by hash (file/symbol/content) → stale | superseded
commit_sha + file_hashes captured host-side (cortex-work-product); /beat/work-products/check-freshness compares hashes; changes mark older briefs stale unless superseded.cortex-brief; re-reading files with current briefs is a workflow failure; >40% re-discovery token spend gets flagged.