Cortex vs Shodh Memory

list_domains

Read profiles.json and emit an overview row for every cognitive domain Cortex has profiled, sorted by session count. Per domain: id, human label, sessionCount, confidence, lastActive, top-3 work categories with ratios, and dominantMode from the session shape. Use this to discover what domains exist before scoping `recall`, `narrate`, or `rebuild_profiles`. Distinct from `query_methodology` (deep profile for ONE domain), `detect_domain` (classifies the current context, no enumeration), and `memory_stats` (memory-system counts, not domain profiles). Read-only. Takes no arguments. Latency <10ms. Returns {domains: [{id, label, sessionCount, confidence, lastActive, topCategories, dominantMode}], totalDomains, globalStyle}.

record_session_end

Record session-end signals (tools used, duration, turns, keywords) and apply an incremental EMA update to the matching domain's cognitive profile. Also stores an episodic session-summary memory, runs a session self-critique (overall score + top improvement suggestions — each non-empty suggestion is ALSO persisted as its own 'lesson-candidate'-tagged memory, M-D6, so it is never lost the moment this call returns), and creates prospective triggers from any TODO/decision keywords detected in the message stream. Normally invoked automatically by the SessionEnd hook — call manually only when reconstructing offline sessions. Distinct from `rebuild_profiles` (full rescan from scratch, throws away the cache) and `query_methodology` (read-only profile retrieval). Mutates profiles.json + session-log.json + memories table. Latency <200ms. Returns {domain, profile_updated, session_score, critique, lessonCandidatesStored, memory_id?}.

explore_features

Inspect the user's cognitive profile through one of four interpretability lenses (mechanistic-interpretability inspired, Bricken et al. 2023): `features` returns the active sparse-dictionary behavioral features for a domain; `attribution` perturbation-traces which input signals drove the domain's profile, sampling up to 20 of that domain's own recent sessions from disk (empty graph if the domain has no indexed sessions -- run rebuild_profiles first); `persona` returns the 12D persona vector with drift-from-baseline; `crosscoder` compares two domains to detect persistent behavioral features. Use this when facing an unfamiliar pattern and you want a behavioral explanation. Distinct from `query_methodology` (full profile, not the interpretability internals) and `list_domains` (overview, no analysis). Read-only on profiles.json. Latency <100ms. Returns mode-specific JSON: {dictionary | graph | persona | comparison}.

remember

Store a memory through the flat 4-signal predictive-coding write gate (embedding, entity, temporal, and structural novelty — Friston-inspired prediction-error gating). Novel surprising content passes; redundant content is rejected or merged with the most-similar existing memory via active curation. After write: thermodynamic tagging, knowledge-graph entity extraction, neuromodulation (DA/NE/ACh/5-HT), engram allocation. FOR A DURABLE CLAIM (a fact, decision, or lesson meant to outlive this session), include a checkable reference in `content` — a file path, a git commit SHA, a URL, or a content-addressed artifact digest — so it can grade above 'unverifiable' (see the `provenance` response field and coding-standards.md §8, 'no source, no implementation'); testimony without one is still stored, just graded accordingly. Use this after any non-trivial discovery, fix, decision, or lesson — if it would surprise a future session, store it. Distinct from `anchor` (pins an EXISTING memory, doesn't create), `wiki_write` (creates an .md page, not a memory row), `validate_memory` (re-grades EXISTING memories with network-verified checks, not a write path), and `add_rule` (recall-time filter, not stored content). Mutates memories + entities + relationships tables. Latency ~50-100ms. Returns {stored, memory_id, action: stored|merged|rejected, reason, provenance}.

recall

Retrieve memories from the Cortex store using intent-adaptive PG recall (server-side WRRF fusion of vector + FTS + trigram + heat + recency) followed by FlashRank cross-encoder reranking and production enrichments (prospective memory injection, Hebbian co-activation strengthening, neuro-symbolic rules, strategic ordering to mitigate Lost-in-the-Middle, Liu et al. 2023). Use this before any non-trivial work to check what Cortex already knows; running blind is unacceptable when recall takes ~200ms. Distinct from `recall_hierarchical` (returns the L0/L1/L2 cluster topology, not a flat ranked list), `navigate_memory` (graph BFS over co-access edges from one seed memory), and `get_causal_chain` (entity-graph traversal, not memory recall). Not read-only: every returned memory is recorded as a hippocampal replay event — access_count/replay_count increment and hippocampal_dependency decays (CLS-B, Ketz et al. 2023) — so repeat calls are not idempotent (`track_replay_event`, `replay_tracking.py`). Returns ranked memories with scores, heat, and source.

memory_stats

Aggregate population diagnostics for the memory system: total / episodic / semantic / active / archived / stale / protected memory counts, average heat, entity and relationship totals, active prospective triggers, last consolidation timestamp, and vector-search availability (pgvector). Use this for health checks, dashboards, or before/after a `consolidate` run to verify cycles fired. Distinct from `assess_coverage` (scored 0-100 with recommendations, this is raw counts), `detect_gaps` (enumerates specific missing things), and `list_domains` (per-domain profile rows, not memory counts). Read-only. Takes no arguments. Latency ~75ms (includes the grooming-staleness ages below). Returns {total_memories, episodic_count, semantic_count, active_count, archived_count, stale_count, protected_count, avg_heat, total_entities, total_relationships, active_triggers, last_consolidation, has_vector_search, grooming_staleness}. `grooming_staleness` carries last-run age (days) for the three judgment-level grooming kinds (wiki/distillation/promotion) against a sourced threshold -- ages only, no backlog counts (those cost ~1s combined; call `get_grooming_health` for the full picture).

checkpoint

Hippocampal-replay-style save/restore of whole working state across context compaction events (McClelland 1995). `save` writes a checkpoint row capturing current task, files-being-edited, key decisions, open questions, planned next steps, and active errors, tied to the current epoch. `restore` reconstructs post-compaction context by fusing the latest checkpoint with anchored + hot + directory-relevant memories. Use `save` before risking compaction; use `restore` immediately after. Distinct from `anchor` (per-memory pinning, no task state), `remember` (creates one memory, no whole-state snapshot), and `query_methodology` (cognitive profile, not session state). Mutates the checkpoints table on save; read-only on restore. Latency ~50ms (save) / ~100ms (restore). Returns {action, checkpoint_id, restored_context?, memories_attached}.

narrative

Generate a coherent project narrative from stored memories for a directory or domain. Clusters memories by topic + time, identifies the through-line, and renders either a multi-section story or (when `brief=true`) a one-paragraph executive summary. Use this for status updates, README seeds, or to onboard a new contributor with the project's actual history. Distinct from `get_project_story` (period-bucketed chronological chapters with explicit time ranges), `assess_coverage` (numeric score, no prose), and `recall` (raw ranked memories). Read-only. Latency ~300-800ms. Returns {narrative, memory_count, themes}.

consolidate

Run scheduled memory-system maintenance cycles: thermodynamic heat decay, full-text → gist → tag compression, episodic→semantic CLS transfer (McClelland 1995), synaptic plasticity LTP/LTD (Hebb 1949, Bi & Poo 1998), microglial pruning of orphan edges (Wang 2020), homeostatic scaling (Turrigiano 2008), cascade stage advancement (Kandel 2001), and optional deep-sleep replay. Each cycle is delegated to a focused sub-module under handlers/consolidation/; durations are tracked per stage with partial-failure rollup. Use this on a daily/weekly cadence (or after large ingest bursts) to keep recall fast and the heat distribution healthy. Distinct from `wiki_consolidate` (operates on wiki PAGES not memories) and `forget` (one-off deletion, no lifecycle). Mutates memories + entities + relationships tables. Latency varies (~5-60s typical, deep mode minutes). Returns per-cycle counters, duration_ms per stage, status (ok|partial), and failed_stages list. The `cls` and `memify` stages include `reason_for_zero` / `reason_for_inaction` when the cycle produces no mutations, distinguishing early-return from a genuine quiet-store pass (issue #14 P2).