TT-Wang/cortex-plugin

Layered recall — session start + in-session overhaul

Comprehensive overhaul of memory retrieval adopting patterns from claude-mem (3-tier progressive disclosure) and mem0 (pre-loaded context + topic-shift detection). Retrieval-layer only — mining, storage, and the Obsidian vault layout are unchanged.

Session start

• SessionStart hook (hooks/session-start.sh) fires before the user types, injecting a compact briefing. Silent by default; MEMEM_SHOW_BANNER=1 for a one-line status banner.
• Compact index injection — each L1-L3 memory contributes ~50 tokens ([id] L<layer> title — snippet) instead of full content. L0 still gets full content.
• L0/L1/L2/L3 auto-stratification via a pure-Python heuristic at mining time (classify_layer). New layer int field in memory frontmatter.

During the session

• 3-tier recall workflow:
  • memory_search(query) → Layer 1 compact index (~50 tok/result)
  • memory_get(ids=[...]) → Layer 2 full content (~500 tok/result)
  • memory_timeline(memory_id) → Layer 3 chronological thread via related[] graph
• Topic-shift detection on UserPromptSubmit. Keyword overlap < 30% re-fires context_assemble for a fresh brief. Closes claude-mem's biggest known weakness ("Claude didn't think to search"). Triggers logged to ~/.memem/topic-shifts.log.
• One-hop graph traversal on memory_search and memory_get — follows the related[] field automatically and includes linked memories.
• Opt-in PreToolUse hook enriches Read tool calls with memories about the target file path. Off by default; enable via MEMEM_PRETOOL_GATING=1.

Backward compat

• memory_recall MCP tool is UNCHANGED and works as a backward-compat alias.
• Existing memories without a layer field parse as L2 (default). No migration needed.
• Legacy CORTEX_* env vars still work.

New env vars (all optional)

• MEMEM_SHOW_BANNER=1 — session-start status banner
• MEMEM_PRETOOL_GATING=1 — file-read enrichment hook
• MEMEM_TOPIC_SHIFT_THRESHOLD=0.3 — topic-shift re-fire threshold (default 0.3)

Tests

• 15 new tests in tests/test_v010.py
• All 58 existing tests still pass → 73/73 green
• Ruff clean across memem/, tests/, hooks/

Upgrading

/plugin update memem

On next session start, memem will auto-inject the new compact index. Memories will reclassify through the miner as they're touched. To force reclassification, run python3 -m memem.server --rebuild-playbooks.