Skip to content

MICA_MEMORY.md

Latest commit

 

History

History
227 lines (149 loc) · 6.85 KB

MICA_MEMORY.md

File metadata and controls

227 lines (149 loc) · 6.85 KB
Raw

STEM BIO-AI MICA Memory Layer

Version: 1.8.4 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.

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.8.4.json
  • memory/stem-ai-playbook.v1.8.4.md
  • memory/stem-ai-lessons.v1.8.4.md

The working tree intentionally keeps only this active trio. Older release-memory snapshots are preserved through Git-tagged release history unless explicitly retired by a documented archive-policy change.

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:

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 provenance is 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:

  • Git-tagged release history remains the archive of prior memory states
  • only memory/mica.yaml decides what is active
  • the visible working-tree surface keeps only the current archive/playbook/lessons trio

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 in tagged Git history rather than as parallel working-tree files unless an explicit archive-policy change says otherwise

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.