feat(memory): episode lifecycle — dedup-on-write + eviction (cap/TTL) (#17)

* feat(memory): episode lifecycle — dedup-on-write + eviction (cap/TTL)

EpisodeStore had no dedup and no eviction: episodes accumulated forever
and near-duplicate sessions piled up unbounded (disk growth, noisier
recall). This adds bounded, de-duplicated episode storage, config-gated
with safe defaults, no on-disk format change.

- Dedup-on-write: a new episode whose cosine similarity to an existing one
  is >= episode_dedup_threshold (default 0.92) REPLACES it (newest-wins).
  Uses an ephemeral RP embedder (the NewRPRanker primitive) over full
  on-disk summaries — never the shared dirty-rebuild vector index, avoiding
  mid-write re-entrancy. Provenance-gated: an untrusted near-dup can never
  evict a trusted/approved episode (trustRank mirrors the recall filter).
- Eviction: prune-on-write applies TTL (episode_ttl_days, default 0/off)
  then a count cap (max_episodes, default 500), deleting both the .md file
  and the index entry. Crash-safe order: files -> writeIndex -> markDirty.
  Also exposes EpisodeStore.Prune() for session-end/CLI use.
- Locking: dedup + .md write + index update + prune + markDirty now happen
  under a single e.mu hold (new writeLocked). Fixes a latent bug where
  re-writing the same sessionID appended a duplicate index entry.
- Config: EpisodeDedupThreshold / MaxEpisodes / EpisodeTTLDays wired through
  MemoryConfig, DefaultMemoryConfig, both overlay sites, and a new
  NewEpisodeStoreWithLifecycle (bare NewEpisodeStore keeps lifecycle off, so
  existing callers/tests are unaffected). Documented in docs/CONFIG.md.

Fact supersession is deferred (facts lack per-entry metadata; already
covered by merge-on-write + session-end LLM consolidation).

Tests: dedup replace/threshold/disabled, provenance safety (both
directions), eviction by count + TTL, TTL-disabled, self-overwrite
regression, evicted-id absent from recall, -race concurrency (16
goroutines), config defaults + overlay-to-store wiring.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(memory): validate sessionID before deleting episode files

Adversarial review (AI Verification Protocol) found a path-traversal
defense-in-depth gap: eviction/dedup called os.Remove on sessionIDs read
straight from index.json without validation, so a crafted/corrupted index
entry (e.g. "../victim") could delete a .md file OUTSIDE the episodes dir.
Every other file op in the package (Read/Write/Promote) already validates.

Add removeEpisodeFile(sessionID) which calls session.ValidateSessionID
before os.Remove, and route all three eviction/dedup deletions through it.
Adds a traversal-safe regression test.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: jkyberneees

docs/CONFIG.md

@@ -203,7 +203,10 @@ The `memory` section controls the persistent memory system (see [docs/MEMORY.md]
     "llm_consolidate": true,
     "merge_threshold": 0.7,
     "add_threshold": 0.3,
-    "auto_approve_episodes": false
+    "auto_approve_episodes": false,
+    "episode_dedup_threshold": 0.92,
+    "max_episodes": 500,
+    "episode_ttl_days": 0
   }
 }
 ```
@@ -225,6 +228,9 @@ The `memory` section controls the persistent memory system (see [docs/MEMORY.md]
 | `merge_threshold` | 0.7 | Cosine similarity above which two fact entries are **auto-merged** without an LLM call (0.0–1.0). Raise it to merge less aggressively; lower it to merge more. |
 | `add_threshold` | 0.3 | Cosine similarity below which a new fact entry is **auto-added** without an LLM call (0.0–1.0). Between `add_threshold` and `merge_threshold` the LLM decides. Keep `add_threshold` < `merge_threshold`. |
 | `auto_approve_episodes` | false | **Security trade-off.** When true, untrusted episodes (sessions that touched web/MCP/out-of-workspace content) are auto-approved at session end so they are recalled without a manual `odek memory promote`. Leaving it `false` keeps the human review gate (recommended). |
+| `episode_dedup_threshold` | 0.92 | Cosine similarity above which a newly written episode is treated as a near-duplicate of an existing one and **replaces** it (newest wins). An untrusted episode never replaces a trusted/approved one. `0` disables dedup. |
+| `max_episodes` | 500 | Maximum number of stored episodes. On each write, episodes beyond this count are evicted oldest-first (both the summary file and the index entry). `0` disables the cap. |
+| `episode_ttl_days` | 0 | Evict episodes older than this many days. `0` (default) disables TTL-based eviction. |
 
 ### ⚠️ `extract_facts` — automatic fact learning (opt-in, off by default)
 

internal/config/loader.go

@@ -859,6 +859,15 @@ func resolveMemory(cfg *memory.MemoryConfig) memory.MemoryConfig {
 	if cfg.AutoApproveEpisodes != nil {
 		def.AutoApproveEpisodes = cfg.AutoApproveEpisodes
 	}
+	if cfg.EpisodeDedupThreshold > 0 {
+		def.EpisodeDedupThreshold = cfg.EpisodeDedupThreshold
+	}
+	if cfg.MaxEpisodes > 0 {
+		def.MaxEpisodes = cfg.MaxEpisodes
+	}
+	if cfg.EpisodeTTLDays > 0 {
+		def.EpisodeTTLDays = cfg.EpisodeTTLDays
+	}
 	return def
 }