superlocalmemory 3.7.7 → 3.8.0

package/src/superlocalmemory/evolution/skill_evolver.py

@@ -46,27 +46,34 @@ from superlocalmemory.evolution.budget import (
     EvolutionBudget,
 )
 from superlocalmemory.evolution.llm_dispatch import _dispatch_llm
+from superlocalmemory.evolution.model_selection import (
+    _MODEL_ALIASES,
+    _resolve_model_alias,
+    resolve_evolution_models,
+)
 
 logger = logging.getLogger(__name__)
 
 EVOLVED_SKILLS_DIR = Path.home() / ".claude" / "skills" / "evolved"
 
-# Short-name → allow-listed model id. Kept narrow so an unknown alias
-# falls through to haiku rather than silently dispatching sonnet.
-_MODEL_ALIASES: dict[str, str] = {
-    "haiku": "claude-haiku-4-5",
-    "sonnet": "claude-sonnet-4-6",
-    "ollama": "ollama:llama3",
-    "ollama:llama3": "ollama:llama3",
-    "ollama:qwen2.5": "ollama:qwen2.5",
-    "claude-haiku-4-5": "claude-haiku-4-5",
-    "claude-sonnet-4-6": "claude-sonnet-4-6",
-}
+# Model aliasing + per-step selection live in ``model_selection`` — a single
+# source of truth shared with the config layer. ``_MODEL_ALIASES`` and
+# ``_resolve_model_alias`` are imported above and re-exported here for
+# callers/tests that still reference them via ``skill_evolver``.
+__all__ = ["SkillEvolver", "detect_backend", "_resolve_model_alias"]
 
 
-def _resolve_model_alias(alias: str) -> str:
-    """Translate a short alias (``haiku``/``sonnet``) to an allow-listed id."""
-    return _MODEL_ALIASES.get(alias, "claude-haiku-4-5")
+def _ollama_running() -> bool:
+    """Return True if a local Ollama daemon answers on the default port."""
+    try:
+        import urllib.request
+        req = urllib.request.Request(
+            "http://127.0.0.1:11434/api/tags", method="GET",
+        )
+        with urllib.request.urlopen(req, timeout=2):  # noqa: S310
+            return True
+    except Exception:
+        return False
 
 
 def detect_backend() -> str:
@@ -81,13 +88,8 @@ def detect_backend() -> str:
         return "claude"
 
     # 2. Ollama running?
-    try:
-        import urllib.request
-        req = urllib.request.Request("http://127.0.0.1:11434/api/tags", method="GET")
-        with urllib.request.urlopen(req, timeout=2):
-            return "ollama"
-    except Exception:
-        pass
+    if _ollama_running():
+        return "ollama"
 
     # 3. API key set?
     if os.environ.get("ANTHROPIC_API_KEY"):
@@ -119,9 +121,11 @@ class SkillEvolver:
         self._db_path = str(db_path)
         self._store = EvolutionStore(db_path)
         self._degradation = DegradationTrigger(db_path)
-        self._health = HealthCheckTrigger(db_path)
+        self._health = HealthCheckTrigger(db_path, profile_id=profile_id)
         self._config = config
         self._backend: str | None = None
+        # ResolvedModels, resolved lazily & cached via _get_models().
+        self._models = None
         self._profile_id = profile_id
         self._current_cycle_id: str | None = None
 
@@ -160,6 +164,26 @@ class SkillEvolver:
         logger.info("Evolution backend: %s", self._backend)
         return self._backend
 
+    def _get_models(self):
+        """Resolve per-step evolution models (cached).
+
+        Defaults to the lowest-cost model for the active backend and keeps
+        the blind verifier independent of the generator where possible
+        (see ``model_selection.resolve_evolution_models``). Falls back to
+        stock ``EvolutionConfig`` defaults when no config is attached.
+        """
+        if self._models is not None:
+            return self._models
+        backend = self._get_backend()
+        evo_cfg = getattr(self._config, "evolution", None)
+        if evo_cfg is None:
+            from superlocalmemory.core.config import EvolutionConfig
+            evo_cfg = EvolutionConfig()
+        self._models = resolve_evolution_models(
+            evo_cfg, backend, ollama_available=_ollama_running(),
+        )
+        return self._models
+
     def run_consolidation_cycle(self, profile_id: str = "default") -> dict:
         """Run during consolidation. Checks triggers 2 and 3.
 
@@ -200,7 +224,7 @@ class SkillEvolver:
         self, profile_id: str, backend: str,
     ) -> dict:
         """Inner consolidation loop — runs under an open budget cycle."""
-        self._store.reset_cycle()
+        self._store.reset_cycle(profile_id)
         results = {"candidates": 0, "evolved": 0, "rejected": 0, "skipped": 0, "backend": backend}
 
         # Prune recovered skills from anti-loop tracking
@@ -215,7 +239,7 @@ class SkillEvolver:
         results["candidates"] = len(candidates)
 
         for candidate in candidates:
-            if not self._store.can_evolve():
+            if not self._store.can_evolve(profile_id):
                 results["skipped"] += len(candidates) - results["evolved"] - results["rejected"]
                 break
 
@@ -271,7 +295,7 @@ class SkillEvolver:
         results["candidates"] = len(candidates)
 
         for candidate in candidates:
-            if not self._store.can_evolve():
+            if not self._store.can_evolve(profile_id):
                 break
             outcome = self._process_candidate(candidate, profile_id)
             if outcome == "evolved":
@@ -281,6 +305,30 @@ class SkillEvolver:
 
         return results
 
+    def evolve_candidate(
+        self, candidate: EvolutionCandidate, profile_id: str = "default",
+    ) -> str:
+        """Evolve a single candidate under a budget cycle (audit-10 fix).
+
+        Public entry point for the ``evolve_skill`` MCP tool. Opening the
+        budget cycle HERE is what makes the per-cycle LLM-call, wall-time and
+        per-day caps apply to manual/MCP-triggered evolution, exactly as they
+        do to consolidation. The MCP tool previously called
+        ``_process_candidate`` directly, so budget charges happened outside a
+        cycle, the guard raised RuntimeError, ``_llm_call`` swallowed it, and
+        every cap was silently bypassed.
+        """
+        try:
+            with self._budget.cycle():
+                self._current_cycle_id = None
+                return self._process_candidate(candidate, profile_id)
+        except BudgetExhausted as exc:
+            logger.info(
+                "evolve_candidate skipped: budget exhausted [%s]",
+                getattr(exc, "dimension", "?"),
+            )
+            return "skipped"
+
     def _process_candidate(
         self, candidate: EvolutionCandidate, profile_id: str,
     ) -> str:
@@ -301,7 +349,7 @@ class SkillEvolver:
         if self._store.is_addressed(candidate.skill_name, context_hash):
             return "skipped"
 
-        if self._store.has_exceeded_attempts(candidate.skill_name):
+        if self._store.has_exceeded_attempts(candidate.skill_name, profile_id):
             logger.info("Skill %s exceeded max attempts, flagging for review", candidate.skill_name)
             return "skipped"
 
@@ -323,7 +371,7 @@ class SkillEvolver:
             original_content=original_content[:2000],
             created_at=now,
         )
-        self._store.save_record(record)
+        self._store.save_record(record, profile_id)
 
         # Step 2: LLM confirmation gate (uses Haiku for cost)
         confirmed = self._llm_confirm(candidate, original_content)
@@ -334,7 +382,7 @@ class SkillEvolver:
                 rejection_reason="LLM confirmation gate rejected",
                 completed_at=datetime.now(timezone.utc).isoformat(),
             )
-            self._store.save_record(record)
+            self._store.save_record(record, profile_id)
             return "rejected"
 
         # Step 3: Generate mutation (uses Sonnet for quality)
@@ -347,7 +395,7 @@ class SkillEvolver:
                 rejection_reason="Mutation generation failed",
                 completed_at=datetime.now(timezone.utc).isoformat(),
             )
-            self._store.save_record(record)
+            self._store.save_record(record, profile_id)
             return "rejected"
 
         # Step 4: Blind verification (uses Haiku — different model from generator)
@@ -365,7 +413,7 @@ class SkillEvolver:
                 blind_verified=False,
                 completed_at=datetime.now(timezone.utc).isoformat(),
             )
-            self._store.save_record(record)
+            self._store.save_record(record, profile_id)
             return "rejected"
 
         # Step 5: Persist evolved skill
@@ -373,7 +421,9 @@ class SkillEvolver:
         skill_path = self._write_evolved_skill(candidate, evolved_content, record_id)
 
         # M-GENERATION: Compute generation from parent's history
-        parent_history = self._store.get_skill_history(candidate.skill_name, limit=1)
+        parent_history = self._store.get_skill_history(
+            candidate.skill_name, profile_id, limit=1,
+        )
         parent_gen = (
             parent_history[0].generation
             if parent_history and parent_history[0].status == EvolutionStatus.PROMOTED
@@ -390,8 +440,8 @@ class SkillEvolver:
             generation=parent_gen + 1,
             completed_at=datetime.now(timezone.utc).isoformat(),
         )
-        self._store.save_record(record)
-        self._store.record_evolution_attempt()
+        self._store.save_record(record, profile_id)
+        self._store.record_evolution_attempt(profile_id)
 
         logger.info(
             "Evolved skill: %s (%s via %s) → %s",
@@ -451,8 +501,20 @@ class SkillEvolver:
                 cycle_id=self._current_cycle_id,
             )
         except ValueError as exc:
-            # Gate rejected — treat like "no LLM available".
-            logger.warning("evolution dispatch rejected: %s", exc)
+            # A ValueError from _dispatch_llm is a CONTRACT breach, not a
+            # runtime/transport failure: forbidden or unlisted model,
+            # non-positive max_tokens, max_tokens over MAX_TOKENS_CAP, or
+            # an empty profile_id. Every one is a misconfiguration in our
+            # own wiring — e.g. a caller requesting more tokens than the
+            # ceiling, which is exactly how mutation generation died
+            # silently for releases. Log at ERROR so it surfaces in logs
+            # and CI instead of masquerading as a normal "no LLM"
+            # fail-closed. Behaviour is unchanged: we still return "" so a
+            # consolidation cycle degrades gracefully rather than crashing.
+            logger.error(
+                "evolution dispatch misconfigured — no evolution this "
+                "call (returning empty string): %s", exc,
+            )
             return ""
         except Exception as exc:  # noqa: BLE001 — fail-closed
             logger.debug("evolution dispatch failed: %s", exc)
@@ -467,16 +529,25 @@ class SkillEvolver:
             f"Should this skill be evolved ({candidate.evolution_type.value})? "
             f"Reply YES or NO with brief reason."
         )
-        response = self._llm_call(prompt, max_tokens=100)
+        response = self._llm_call(
+            prompt, max_tokens=100, model=self._get_models().confirm,
+        )
         if not response:
             logger.warning("LLM confirmation gate: empty response, skipping evolution for %s", candidate.skill_name)
             return False  # Fail-closed: no LLM = no evolution
         return "yes" in response.lower()
 
     def _generate_mutation(self, prompt: str) -> Optional[str]:
-        """Generate evolved SKILL.md (uses sonnet for quality)."""
+        """Generate evolved SKILL.md via the configured mutation model.
+
+        Defaults to the lowest-cost model for the backend (v3.7.9);
+        users can opt up (e.g. to sonnet) via ``evolution.mutation_model``.
+        """
+        mutation_model = self._get_models().mutation
         for attempt in range(mutgen.MAX_APPLY_RETRIES):
-            response = self._llm_call(prompt, max_tokens=4000, model="sonnet")
+            response = self._llm_call(
+                prompt, max_tokens=4000, model=mutation_model,
+            )
             if not response:
                 return None
             content = mutgen.parse_mutation_output(response)
@@ -492,8 +563,15 @@ class SkillEvolver:
         return None
 
     def _blind_verify(self, prompt: str) -> verifier.VerificationResult:
-        """Blind verification."""
-        response = self._llm_call(prompt, max_tokens=500)
+        """Blind verification — runs on a model independent of the generator.
+
+        See ``model_selection.resolve_evolution_models``: the verify model
+        is kept different from the mutation model where possible so the
+        generator can't grade its own homework.
+        """
+        response = self._llm_call(
+            prompt, max_tokens=500, model=self._get_models().verify,
+        )
         if not response:
             return verifier.VerificationResult(
                 passed=False, confidence=0.0, reasoning="No LLM response",
@@ -545,8 +623,11 @@ class SkillEvolver:
         """Write evolved SKILL.md to ~/.claude/skills/evolved/."""
         EVOLVED_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
 
-        # Build directory name
-        base_name = candidate.skill_name.replace(":", "-")
+        # Build directory name. skill_name derives from a behavioral-assertion
+        # trigger (any non-whitespace), so sanitize for ALL evolution types —
+        # "../../.claude/settings" must not escape EVOLVED_SKILLS_DIR.
+        base_name = re.sub(r"[^a-zA-Z0-9_-]", "-",
+                           candidate.skill_name).lower()[:50] or "skill"
         if candidate.evolution_type == EvolutionType.FIX:
             dir_name = f"{base_name}-v{record_id[:6]}"
         elif candidate.evolution_type == EvolutionType.DERIVED:
@@ -556,8 +637,12 @@ class SkillEvolver:
             dir_name = re.sub(r"[^a-zA-Z0-9_-]", "-", dir_name).lower()[:50]
         else:
             dir_name = base_name
+        dir_name = dir_name or "skill"
 
         skill_dir = EVOLVED_SKILLS_DIR / dir_name
+        # Defense in depth: never write outside the evolved-skills directory.
+        if not str(skill_dir.resolve()).startswith(str(EVOLVED_SKILLS_DIR.resolve())):
+            raise ValueError(f"evolved skill path escapes sandbox: {dir_name!r}")
         skill_dir.mkdir(parents=True, exist_ok=True)
 
         skill_path = skill_dir / "SKILL.md"

package/src/superlocalmemory/evolution/triggers.py

@@ -294,17 +294,19 @@ class HealthCheckTrigger:
 
     _STATE_KEY = "health_check_cycle_count"
 
-    def __init__(self, db_path: str | Path):
+    def __init__(self, db_path: str | Path, profile_id: str = "default"):
         self._db_path = str(db_path)
+        self._profile_id = profile_id or "default"
         self._check_every_n = 3  # Every 3rd consolidation (~18h)
 
     def _read_cycle_count(self) -> int:
-        """Read persisted cycle count from DB."""
+        """Read this profile's persisted cycle count."""
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             row = conn.execute(
-                "SELECT value FROM evolution_cycle_state WHERE key = ?",
-                (self._STATE_KEY,),
+                "SELECT value FROM evolution_cycle_state "
+                "WHERE profile_id = ? AND key = ?",
+                (self._profile_id, self._STATE_KEY),
             ).fetchone()
             return int(row[0]) if row else 0
         except sqlite3.OperationalError:
@@ -314,23 +316,30 @@ class HealthCheckTrigger:
             conn.close()
 
     def _write_cycle_count(self, count: int) -> None:
-        """Persist cycle count to DB.
+        """Persist this profile's cycle count.
 
-        Relies on evolution_cycle_state table created by EvolutionStore.
-        Falls back to CREATE IF NOT EXISTS for standalone use.
+        The evolution_cycle_state table (profile_id, key) is created by
+        EvolutionStore with the correct composite-PK schema — we do NOT
+        CREATE it here (the old single-key CREATE produced a conflicting
+        schema and cross-profile collisions).
         """
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
-            # Table schema matches evolution_store.py: value INTEGER
+            # Correct composite-PK schema (matches EvolutionStore). Created only
+            # for standalone use (tests); a real deployment already has it.
             conn.execute(
-                "CREATE TABLE IF NOT EXISTS evolution_cycle_state "
-                "(key TEXT PRIMARY KEY, value INTEGER DEFAULT 0, updated_at TEXT)",
+                "CREATE TABLE IF NOT EXISTS evolution_cycle_state ("
+                "profile_id TEXT NOT NULL DEFAULT 'default', key TEXT NOT NULL, "
+                "value INTEGER DEFAULT 0, updated_at TEXT, "
+                "PRIMARY KEY (profile_id, key))",
             )
             now = datetime.now(timezone.utc).isoformat()
             conn.execute(
-                "INSERT OR REPLACE INTO evolution_cycle_state (key, value, updated_at) "
-                "VALUES (?, ?, ?)",
-                (self._STATE_KEY, count, now),
+                "INSERT INTO evolution_cycle_state (profile_id, key, value, updated_at) "
+                "VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(profile_id, key) DO UPDATE SET "
+                "value=excluded.value, updated_at=excluded.updated_at",
+                (self._profile_id, self._STATE_KEY, count, now),
             )
             conn.commit()
         except sqlite3.OperationalError as exc:

package/src/superlocalmemory/graph/cozo_backend.py

@@ -672,32 +672,34 @@ class CozoDBGraphBackend:
     # Tier Sync
     # ------------------------------------------------------------------
 
+    # Rebind the whole entity row (Cozo has no partial ``:update`` op — that
+    # token does not parse) while binding the id/tier/timestamp as query
+    # parameters so an entity id containing a quote can never become Datalog.
+    # The ``*entity{...}`` match means non-existent ids are a safe no-op rather
+    # than creating a stub row.
+    _TIER_SYNC_QUERY = (
+        "?[id, name, entity_type, tier, properties, profile_id, created_at, updated_at] := "
+        "*entity{id, name, entity_type, properties, profile_id, created_at}, "
+        "id = $id, tier = $tier, updated_at = $now "
+        ":put entity {id => name, entity_type, tier, properties, profile_id, created_at, updated_at}"
+    )
+
     def sync_tier_changes(
         self, added: list[str], removed: list[str]
     ) -> None:
-        """Sync tier changes: add promoted entities, mark demoted."""
+        """Sync tier changes: promote added entities to active, demote removed to cold."""
         now = datetime.now().isoformat()
-
-        if added:
-            # Fetch entity data from existing CozoDB entities or set defaults
-            for entity_id in added:
-                try:
-                    self._db.run(f"""
-                        ?[id, tier] <- [['{entity_id}', 'active']]
-                        :update entity {{id => tier, updated_at: '{now}'}}
-                    """)
-                except Exception:
-                    pass
-
-        if removed:
-            for entity_id in removed:
+        for entity_ids, tier in ((added, "active"), (removed, "cold")):
+            for entity_id in entity_ids:
                 try:
-                    self._db.run(f"""
-                        ?[id, tier] <- [['{entity_id}', 'cold']]
-                        :update entity {{id => tier, updated_at: '{now}'}}
-                    """)
+                    self._db.run(
+                        self._TIER_SYNC_QUERY,
+                        {"id": entity_id, "tier": tier, "now": now},
+                    )
                 except Exception:
-                    pass
+                    logger.debug(
+                        "cozo tier sync skipped for entity %s", entity_id, exc_info=True
+                    )
 
     # ------------------------------------------------------------------
     # Health Check
@@ -712,12 +714,20 @@ class CozoDBGraphBackend:
             edge_count = self._db.run(
                 "?[count(from_id)] := *edge{from_id}"
             )
+            # fact_entity bridge rows (fact_id, entity_id) — counted so parity
+            # verification can catch a silent bridge-import failure that would
+            # otherwise leave Cozo entity recall returning empty results.
+            fe_count = self._db.run(
+                "?[count(fact_id)] := *fact_entity{fact_id, entity_id}"
+            )
             ec = entity_count.values.tolist()[0][0] if len(entity_count) > 0 else 0
             edc = edge_count.values.tolist()[0][0] if len(edge_count) > 0 else 0
+            fec = fe_count.values.tolist()[0][0] if len(fe_count) > 0 else 0
             return {
                 "status": "active",
                 "entities": int(ec),
                 "edges": int(edc),
+                "fact_entity": int(fec),
                 "shadow_checks": self._shadow_checks,
                 "shadow_mismatches": self._shadow_mismatches,
                 "shadow_errors": self._shadow_errors,
@@ -730,6 +740,19 @@ class CozoDBGraphBackend:
                 "db_path": self._db_path,
             }
 
+    def entity_ids(self, limit: int = 1000) -> list[str]:
+        """Return up to ``limit`` entity IDs, for scale-engine content parity.
+
+        Count parity alone cannot prove the import reproduced the right rows;
+        comparing this ID set against canonical SQLite catches an import that
+        landed the correct *number* of entities with wrong identities.
+        """
+        try:
+            res = self._db.run("?[id] := *entity{id} :limit " + str(int(limit)))
+            return [row[0] for row in res.values.tolist()]
+        except Exception:
+            return []
+
     # ------------------------------------------------------------------
     # Rebuild (from SQLite canonical)
     # ------------------------------------------------------------------

package/src/superlocalmemory/hooks/adapter_base.py

@@ -38,7 +38,11 @@ from typing import Protocol, runtime_checkable
 # ---------------------------------------------------------------------------
 
 HARD_BYTES_CAP = 4096
-COPILOT_SOFT_BYTES = 2048
+# Soft budget for the managed instruction block. Raised 2048 -> 2560 -> 2816 as
+# the block grew to carry the memory, token-optimization, and (compact)
+# bounded-loop protocols; the 4 KB hard cap still bounds total size (recall
+# content is truncated to stay under it).
+COPILOT_SOFT_BYTES = 2816
 TRUNCATION_MARKER = b"\n<!-- truncated -->"
 
 

package/src/superlocalmemory/hooks/auto_recall.py

@@ -10,6 +10,7 @@ import logging
 from typing import Any, Callable
 
 from superlocalmemory.core.injection import InjectableMemory, render_context
+from superlocalmemory.retrieval.temporal_frame import relative_age, temporal_frame
 
 logger = logging.getLogger(__name__)
 
@@ -85,7 +86,13 @@ class AutoRecall:
                 )
                 for r in relevant[:self._max_memories]
             ]
-            return render_context(memories, mode="B", cfg=None, wrap=True)
+            ctx = render_context(memories, mode="B", cfg=None, wrap=True)
+            # T-inject: anchor the injected memories to "now" so a time-blind
+            # model can weigh recency. Prepend a one-line temporal frame.
+            frame = temporal_frame(
+                [getattr(r.fact, "created_at", "") for r in relevant[:self._max_memories]]
+            )
+            return f"{frame}\n\n{ctx}" if ctx else ctx
         except Exception as exc:
             logger.warning("Auto-recall failed: %s", exc)
             return ""
@@ -104,12 +111,17 @@ class AutoRecall:
             response = self._recall(query, self._max_memories)
             if response is None:
                 return []
+            from datetime import datetime as _dt, timezone as _tz
+            _now = _dt.now(_tz.utc)
             results = []
             for r in response.results:
                 if r.score >= self._threshold:
+                    _created = getattr(r.fact, "created_at", "") or ""
                     results.append({
                         "fact_id": r.fact.fact_id,
                         "content": r.fact.content[:300],
+                        "created_at": _created,
+                        "age_label": relative_age(_created, _now),
                         "score": round(r.score, 3),
                         "relevance_score": round(
                             getattr(r, "relevance_score", r.score) or 0.0, 3

package/src/superlocalmemory/hooks/claude_code_hooks.py

@@ -261,6 +261,17 @@ def _hook_definitions(include_gate: bool = False) -> dict[str, list]:
                         "command": _wrap_python_cmd("stop_outcome"),
                         "timeout": 10000,
                     },
+                    # Commit temporal summaries so session decisions survive beyond
+                    # the git-state snapshot written by `slm hook stop`.
+                    {
+                        "type": "command",
+                        "command": (
+                            'cmd /c "slm session close 2>NUL || exit /b 0"'
+                            if sys.platform == "win32"
+                            else "slm session close 2>/dev/null || true"
+                        ),
+                        "timeout": 15000,
+                    },
                 ]
             }
         ],

package/src/superlocalmemory/hooks/codex_assets.py

@@ -7,10 +7,16 @@ import sysconfig
 from pathlib import Path
 
 SKILLS = ("slm-cache", "slm-compress", "slm-graph", "slm-recall", "slm-remember", "slm-session", "slm-status")
-AGENTS = {
-    "slm-memory-advisor.toml": 'name = "slm-memory-advisor"\ndescription = "Use SuperLocalMemory safely: initialize once, recall before remember, and store only durable atomic facts."\ninstructions = "Use SLM for memory discipline only. Check results before claiming success; preserve private scope unless the user explicitly asks to share."\n',
-    "slm-optimize-advisor.toml": 'name = "slm-optimize-advisor"\ndescription = "Analyze SuperLocalMemory retrieval, ingestion, cache, compression, and optimization evidence."\ninstructions = "Inspect real SLM evidence before advising. Separate observed performance from targets and recommend measurable experiments."\n',
-}
+
+# Codex subagent files written to ~/.codex/agents (content built by _agent_files()).
+AGENTS = ("slm-memory-advisor.toml", "slm-optimize-advisor.toml")
+
+_MEMORY_ADVISOR_TOML = (
+    'name = "slm-memory-advisor"\n'
+    'description = "Use SuperLocalMemory safely: initialize once, recall before remember, and store only durable atomic facts."\n'
+    'instructions = "Use SLM for memory discipline only. Check results before claiming success; preserve private scope unless the user explicitly asks to share."\n'
+)
+
 
 def _source_root() -> Path:
     development = Path(__file__).resolve().parents[3] / "plugin-src" / "skills"
@@ -21,6 +27,57 @@ def _source_root() -> Path:
         return installed
     raise FileNotFoundError("Bundled Codex skills were not found in this installation")
 
+
+def _agents_source_root() -> Path | None:
+    development = Path(__file__).resolve().parents[3] / "plugin-src" / "agents"
+    if development.exists():
+        return development
+    installed = Path(sysconfig.get_path("data")) / "share" / "superlocalmemory" / "codex" / "agents"
+    return installed if installed.exists() else None
+
+
+def _optimize_advisor_toml() -> str:
+    """Build the optimize-advisor TOML from the canonical advisor doc so Codex
+    ships the FULL decision rules (the 8-rule tree), not a one-line stub. Falls
+    back to a short instruction only if the source doc is unavailable.
+    """
+    description = (
+        "Apply SuperLocalMemory's no-proxy context-optimization rules — reversible "
+        "compression of large tool output and KV-caching of repeated reads/searches."
+    )
+    body = ""
+    root = _agents_source_root()
+    if root is not None:
+        src = root / "slm-optimize-advisor.md"
+        if src.exists():
+            text = src.read_text(encoding="utf-8")
+            if text.startswith("---"):  # strip YAML frontmatter, keep the guidance body
+                end = text.find("\n---", 3)
+                if end != -1:
+                    text = text[end + 4:]
+            body = text.strip()
+    if not body:
+        body = (
+            "Reduce context-window pressure with the Surface-B tools (reversible CCR "
+            "compression + a per-agent KV cache); fail-open — never block the task."
+        )
+    # TOML literal multi-line string ('''...'''): no escape processing, and the
+    # advisor body contains no ''' sequence.
+    return (
+        'name = "slm-optimize-advisor"\n'
+        f'description = "{description}"\n'
+        f"instructions = '''\n{body}\n'''\n"
+    )
+
+
+def _agent_files() -> dict:
+    """Return {filename: TOML content} for the Codex subagents."""
+    return {
+        "slm-memory-advisor.toml": _MEMORY_ADVISOR_TOML,
+        "slm-optimize-advisor.toml": _optimize_advisor_toml(),
+    }
+
+
 def install_assets(*, home: Path | None = None, dry_run: bool = False) -> dict:
     """Copy only named SLM assets; never rewrite user-owned assets."""
     home = home or Path.home()
@@ -37,10 +94,11 @@ def install_assets(*, home: Path | None = None, dry_run: bool = False) -> dict:
         target = skills_root / skill
         target.mkdir(parents=True, exist_ok=True)
         shutil.copy2(source / skill / "SKILL.md", target / "SKILL.md")
-    for filename, content in AGENTS.items():
+    for filename, content in _agent_files().items():
         (agents_root / filename).write_text(content, encoding="utf-8")
     return {"success": True, "skills": list(SKILLS), "agents": list(AGENTS), "dry_run": False}
 
+
 def remove_assets(*, home: Path | None = None, dry_run: bool = False) -> dict:
     """Remove only the known SLM directories and files."""
     home = home or Path.home()
@@ -52,6 +110,7 @@ def remove_assets(*, home: Path | None = None, dry_run: bool = False) -> dict:
             shutil.rmtree(target) if target.is_dir() else target.unlink()
     return {"success": True, "removed": [str(x) for x in existing], "dry_run": dry_run}
 
+
 def status_assets(*, home: Path | None = None) -> dict:
     home = home or Path.home()
     skills = [x for x in SKILLS if (home / ".agents" / "skills" / x / "SKILL.md").exists()]