# STEM BIO-AI MICA Memory Layer Version: 1.8.0 MICA Contract: 0.2.4 Status: Active operational memory contract --- ## Purpose The `memory/` directory is the MICA memory layer for STEM BIO-AI. It is not a generated cache. It is not disposable release residue. It is not a substitute for the public result schema. Its role is to: - pin the active protocol state for agent sessions - preserve versioned archive snapshots across releases - keep drift rules, lessons, and operating playbooks aligned with the current release - provide a portable invocation contract for session startup - provide package-contract self-tests through the MICA PCT runner The active memory layer is selected by [memory/mica.yaml](../memory/mica.yaml). --- ## What Changed In The 0.2.4 Uplift STEM BIO-AI already had a working memory package before this upgrade. This release does **not** replace the archive model. It upgrades the package to the non-breaking `MICA v0.2.4` runtime and validation contract. That means: - `memory/mica.yaml` now declares `mica_spec: "0.2.4"` - the active archive JSON now carries `mica_spec` / `mica_schema_version` `0.2.4` - `tools/mica_pct.py` is available for package validation - `tools/mica_runtime.py` is available for portable runtime summaries - `invocation_protocol.hook_output` is now declared in `memory/mica.yaml` - DI `binding` remains a progressive maturity feature, not a forced rewrite This is a runtime/contract uplift, not a wholesale archive redesign. --- ## Single Source Of Truth `memory/mica.yaml` is the active composition contract. It selects exactly three live files: - archive JSON - playbook markdown - lessons markdown For the current release the active set is: - `memory/stem-ai.mica.v1.7.8.json` - `memory/stem-ai-playbook.v1.7.8.md` - `memory/stem-ai-lessons.v1.7.8.md` Anything older in `memory/` is retained as archive history unless explicitly retired. --- ## Runtime Tooling Two runtime tools are now part of the package: - `python tools/mica_pct.py .` - `python tools/mica_runtime.py . --format text` - `python tools/mica_runtime.py . --format session-report` - `python tools/mica_invoke.py . --mode guided --format json` - `mica_invoke.bat . --mode forced` Recommended session-start sequence: 1. load `memory/mica.yaml` 2. run `python tools/mica_pct.py .` 3. run `python tools/mica_runtime.py . --format text` 4. run `python tools/mica_runtime.py . --format session-report` 5. if the host supports preflight, use `python tools/mica_invoke.py . --mode guided --format json` 6. if the session must be hard-gated, start via `mica_invoke.bat . --mode forced` 7. load the archive referenced by `mica.yaml` 8. load the playbook referenced by `mica.yaml` 9. load lessons on demand Expected posture: - PCT-001 through PCT-004 must be clean - PCT-007 / PCT-009 should indicate a closed package - PCT-010 WARN is acceptable during progressive DI binding rollout - PCT-011 WARN is acceptable only when a declared `lesson_ref` path has not yet been repaired --- ## DI Binding Maturity Boundary MICA `v0.2.4` adds stronger support for DI binding, but STEM BIO-AI is using it in the intended conservative way. Critical design invariants are **not** being mass-rewritten with speculative binding blocks. The rule is: - add `binding.origin_episode` when a real violation or operating lesson exists - add `binding.lesson_ref` only when the referenced lesson file actually exists - do not fabricate incident lineage just to satisfy a schema This keeps the memory layer evidence-based rather than ceremonial. --- ## Hook Output Policy The active `invocation_protocol` keeps: - `primary_pattern: readme_protocol` So normal STEM BIO-AI sessions do **not** require a hook-capable runtime. However, `hook_output` is now declared for forward portability: ```yaml hook_output: max_di_lines: 3 di_filter: violations_only ``` Meaning: - future hook adapters can emit terse summaries - low-signal stable DIs do not flood the session preamble - violated critical invariants stay visible first This is a portability improvement, not a change to scan semantics. --- ## README And SKILL Relationship There are two different entry surfaces: - `README.md`: public project contract and operator-facing overview - `SKILL.md`: agent-facing entry point and load order They should not duplicate full memory contents. They should point to the active contract. Required linkage: 1. `README.md` links here for memory policy. 2. `SKILL.md` tells agents to load `memory/mica.yaml` first. 3. `SKILL.md` should prefer the files referenced by `mica.yaml` rather than hard-coding stale filenames. 4. `SKILL.md` should reference the current PCT range and current `[MICA READY]` output surface. --- ## Retention Policy Historical memory snapshots are intentionally kept in Git. Reasons: - they are part of release provenance - they preserve drift history and patch rationale - they allow exact reconstruction of prior agent operating state Because of that, `memory/` should not be added to `.gitignore`. What stays stable: - old versioned memory files remain as archive - only `memory/mica.yaml` decides what is active What changes on each release-memory rotation: - `memory/mica.yaml` - the new versioned archive/playbook/lessons trio - any doc or skill surface that hard-codes active memory filenames --- ## Release Checklist When the release version changes and memory is updated: 1. create new versioned memory snapshots from the previous active layer 2. update release-specific version strings inside the new snapshots 3. point `memory/mica.yaml` to the new active files 4. verify `SKILL.md` still follows `mica.yaml` 5. run `python tools/mica_pct.py .` 6. run `python tools/mica_runtime.py . --format text` 7. verify README and docs still point to the current memory policy 8. keep older snapshots unless there is an explicit archive-pruning decision --- ## Sanity Checks Minimum checks for the memory layer: - `memory/mica.yaml` exists - each required layer path in `mica.yaml` exists - the archive `project.version` matches the current release - `mica_spec` aligns between `mica.yaml` and the active archive - `SKILL.md` does not hard-code stale active memory filenames - `README.md` links to the current MICA policy doc - `python tools/mica_pct.py .` returns a closed package state --- ## Non-Goals The MICA layer does not: - replace the public API contract - replace `README.md` - define score math by itself - justify hiding old memory files from version control - turn the scanner into a runtime enforcement engine It is an operational memory contract for agent sessions, not a substitute for the scanner's public result schema.