docs/MICA_MEMORY.md

# 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.