Marina

A unified, extensible metacognitive system — downloadable via npm and pip, scriptable, and ready for research.

v0.7.0 (Beta) — Marina implements key elements of the CARINA 12 bio-inspired metacognitive cognitive architecture (BIMCA). It provides a single integrated core (MarinaAgent) combining:

• DMA (Dendritic Metacognitive Architecture): biophysical stability-plasticity primitives.
• Meta-DNA: regulatory "genome" with Model of the Self, pathways, epigenetic traces (χ), and Algorithm 1 approximation with overhead and modulation.
• MCP (Metacognitive Control Plane): decision-theoretic executive with rich actions.
• Pluggable Task Substrate: Working Memory (multi-buffer with load and focus modulation), Episodic Memory (with DMA engrams), Semantic Memory (activation + spreading simulation), Procedural Memory (utilities + conflict resolution). Retrieval bias is pre-computed and influences action selection from the first step.

Marina is designed for researchers to run, inspect, reproduce, and extend experiments with memory-modulated decisions, regulatory overhead, and custom environments. The TypeScript core is the reference implementation for paper fidelity; the Python package provides convenient parity for scripting and teaching.

One install. One core. Multiple interfaces (CLI, Python, JS, full web lab from source).

1. Qué es Marina / What is Marina

Marina is not a collection of independent tabs or demos.

It is one downloadable system whose heart is MarinaAgent:

• DMA (Dendritic Metacognitive Architecture): biophysically-grounded stability-plasticity via apical HCN channels. Real reversal recovery dynamics (<10 steps in paper-aligned regimes).
• Meta-DNA: GRN-inspired regulatory layer. Model of the Self (u,l,p,e,z), transcription factors, meta-genes, co-expressed pathways, and persistent epigenetic traces (χ) — the "cognitive development" mechanism.
• MCP (Metacognitive Control Plane): 1-step lookahead EU with 5+ meta-actions, risk/uncertainty/cost calibration.

Cross-layer effects are real (active pathways modulate DMA tauM and MCP risk; DMA deltas feed MoS uncertainty). The UI tabs are high-fidelity scientific visualizations that can be driven from the single unified core (see "Sync to Tabs").

Goal for 1.0: professional CLI + excellent onboarding + unmistakable "I am using one system" feeling.

Installation

npm (recommended for research fidelity and full features)

The npm package provides the canonical TypeScript implementation (reference for paper fidelity, full biophysical dynamics, and complete cross-layer modulation).

# Global install (recommended for CLI)
npm install -g marinaedutlan

# Or local / one-off
npx marinaedutlan

Requirements: Node.js >= 18.

After installation, marina (or npx marinaedutlan) launches a professional welcome banner, runs a quick 40-step integrated episode using the unified MarinaAgent, and displays a boxed summary with key metrics (uncertainty, performance, active pathways, DMA/MCP state, substrate metrics, last retrieval bias, etc.).

PyPI (Python package — convenient scripting and teaching)

The Python package (pip install marinaedutlan) provides a usable implementation of the same MarinaAgent core (DMA + Meta-DNA + MCP + pluggable Task substrate with retrieval bias, evaluate/runOnTask, persistence, self-audit, etc.). It is ideal for quick experiments, teaching, and environments where Node is not preferred.

Important: The distribution name on PyPI is marinaedutlan (to avoid collision with an unrelated "marina" project). After install you import as marina:

pip install marinaedutlan

# Run a 100-step episode (CLI)
marina
# or
marinaedutlan

# Or programmatic (both forms work)
python -c "
from marina.core import MarinaAgent
# or: from marina import MarinaAgent
agent = MarinaAgent()
agent.run_episode(100)
print(agent.get_summary())
"

Requirements: Python >= 3.9 + click.

Fidelity note: Both the npm and PyPI packages now deliver a high-fidelity implementation of the same unified MarinaAgent (DMA + Meta-DNA + MCP + rich cognitive substrate with pre-computed retrieval bias, Algorithm 1 regulation, pluggable Task, and persistence). The TypeScript version is the primary reference for the most precise biophysical constants and paper-aligned numbers. The Python version provides full practical parity for experiments, custom Tasks, profiles, and research use.

Full scientific web laboratory (from source)

For the complete interactive lab (high-fidelity layer visualizations, "Sync to Tabs", paper browser, Gemini Mirror Test, episode results with rich metrics):

git clone https://github.com/cristianmi24/Marina.git
cd Marina
npm install
npm run dev

The published packages intentionally ship only the lightweight core + CLI (no heavy UI assets) to keep distribution small and focused on the unified agent.

Optional: GEMINI_API_KEY for live Mirror Test queries in the full lab.

Quick Start

CLI (immediate value)

marina
# or
marina run --steps 120
marina run --steps 80 --json

You will see a professional banner, a real integrated episode using MarinaAgent, and a clean summary including:

• Core states (uncertainty, performance, satisfaction, active pathways)
• DMA (gHCN, tauM, beta)
• MCP (quality, risk)
• Substrate metrics (WM load, episodic engrams, semantic activation, procedural productions)
• lastRetrievalBias and lastProposedAction (how memory influenced the decision)
• Self-audit problems and epistemic utility

Programmatic Usage

Python

from marina.core import MarinaAgent
# or: from marina import MarinaAgent

agent = MarinaAgent()
agent.run_episode(150)
print(agent.get_summary())
# Includes: taskType, lastRetrievalBias, lastProposedAction, activePathways, alg1Overhead, etc.

JavaScript / TypeScript (canonical reference)

import { MarinaAgent } from "marinaedutlan/core";

const agent = new MarinaAgent("Planner");
agent.runEpisode(150);
console.log(agent.getSummary());

Headless/scripting use is recommended for research and reproducible experiments.

Features (aligned with CARINA 12 vision)

Marina provides a runnable, extensible seed of a bio-inspired metacognitive cognitive architecture:

• Unified Core (MarinaAgent): DMA + Meta-DNA (Model of the Self, pathways, epigenetic traces χ, Algorithm 1 approximation with overhead and direct modulation of WM/productions) + MCP.
• Pluggable Task Substrate:
  • Working Memory: multi-buffer (Goal/Retrieval/Perceptual/Motor/Imaginal) with load signals and pathway-driven focus modulation.
  • Episodic Memory: DMA engrams + retrieval/use/consolidate + metamemory.
  • Semantic Memory: activation + spreading simulation (outcome/delta similarity + recency).
  • Procedural Memory: utilities, conflict resolution, firing with effects, Meta-DNA modulation.
• Memory-influenced decisions: Retrieval bias is pre-computed at the beginning of each step from semantic and episodic memory and directly biases the action proposed to the Task (exposed as lastRetrievalBias and lastProposedAction).
• Experimentation tools: evaluate(task, steps, options) and runOnTask(task, steps) return rich results including self-audit, substrate snapshots, and history.
• Self-monitoring: Enriched IM-Onto-style self-audit (KTP/DRFP/ADTP) and epistemic utility signals.
• Persistence: Epigenetic state (χ traces) for cross-episode "cognitive development".

The TypeScript core is the reference implementation for paper fidelity. The Python package provides convenient parity on the extensible features (Task, bias, evaluate, runOnTask, last* fields).

Academic Context

This work follows the CARINA 12 — Bio-Inspired Metacognitive Cognitive Architecture plan and related papers on Dendritic Metacognition (DMA) and Meta-DNA regulatory genomes (see papers/ folder).

It demonstrates:

• A unified substrate + regulatory genome + executive plane.
• Pre-computed retrieval bias influencing action selection (memory-first decisions).
• Algorithm 1-style regulation with measurable overhead and modulation of working memory and procedural utilities.
• Easy custom-task experimentation so researchers can study how memory and regulation affect behavior in their own environments.

Current status (transparent): Core architectural elements and practical extensibility are implemented and well integrated. Full classical CA substrate details (rich spreading activation, complete procedural compilation), exact paper Algorithm 1, and comprehensive P1–P4 ablation harnesses remain areas of ongoing/future work.

Advanced Usage — Custom Tasks & Experiments

The pluggable Task system is one of Marina’s most powerful practical features.

JavaScript / TypeScript (recommended form)

import { MarinaAgent } from "marinaedutlan/core";

// Preferred: use the factory (guarantees correct Task shape)
const myTask = MarinaAgent.createSimpleTask((ctx) => {
  // ctx includes: step, retrievalBias, proposedAction, dmaState, ...
  const base = (ctx.step % 4 === 0 ? 0.75 : 0.35);
  return { reward: base + (ctx.retrievalBias || 0) * 0.9 };
});

const agent = new MarinaAgent("Planner", myTask);
const result = agent.evaluate(null, 50, { includeHistory: true });

console.log("avgOutcome:", result.avgOutcome);
console.log("lastRetrievalBias:", result.finalSummary.lastRetrievalBias);
console.log("lastProposedAction:", result.finalSummary.lastProposedAction);

// You can also swap tasks at runtime:
agent.setTask(MarinaAgent.createSimpleTask(ctx => 0.5));
const proposal = agent.proposeAction();

Python (equivalent)

from marina.core import MarinaAgent

def my_task(ctx):
    base = 0.75 if ctx.get("step", 0) % 4 == 0 else 0.35
    return {"reward": base + (ctx.get("retrievalBias") or 0) * 0.9}

agent = MarinaAgent(task=MarinaAgent.create_simple_task(my_task))
result = agent.evaluate(steps=50)

print(result["avgOutcome"], result["lastRetrievalBias"])

# Runtime swap + proposeAction
agent.set_task(MarinaAgent.create_simple_task(lambda ctx: 0.5))
proposal = agent.propose_action()

You can also use agent.runOnTask(...) / agent.run_on_task(...) (temporary task for one evaluation) and agent.proposeAction() / agent.propose_action().

Inspecting state

s = agent.get_summary()
print(s["lastRetrievalBias"], s["lastProposedAction"], s["workingMemoryLoad"])

This design makes it straightforward to study how memory pressure, semantic activation, and regulatory overhead shape behavior in your own tasks.

Limitations (transparent)

• Both packages now deliver a high-fidelity implementation of the integrated MarinaAgent (full substrate with WM/Episodic/Semantic/Procedural, pre-computed retrieval bias, Algorithm 1 regulation with overhead and modulations, rich MCP dispatch). The TypeScript reference remains the gold standard for the most precise paper constants and edge-case biophysical behavior.
• Some advanced classical CA details (full production compilation, extremely rich spreading activation in all scenarios) are implemented at a high practical level but remain areas of ongoing refinement per the CARINA12 plan.
• The full interactive scientific laboratory (Sync to Tabs, advanced visualizations, paper explorer) is available when running from source. The published packages focus on the professional unified core + CLI for easy distribution and experimentation.
• For the absolute latest research-grade numbers from the papers, the TS core (npm) is recommended; Python provides excellent practical parity for most research, teaching, and custom-task work.

Building from Source (Full Web Laboratory)

git clone https://github.com/cristianmi24/Marina.git
cd Marina
npm install
npm run dev          # launches the full web lab
# or
npm run build:core   # only the distributable core

References

• CARINA12_IMPLEMENTATION_PLAN.md and related documents in /papers/
• Dendritic Metacognition (DMA) paper
• Meta-DNA regulatory genome work (BICA)
• IJCAI MCP / CARINA 11 papers

License

MIT (see LICENSE). Research use, contributions, and citations of the CARINA line are welcome.

For the complete interactive lab:

git clone https://github.com/cristianmi24/Marina.git
cd Marina && npm install && npm run dev

Inside the lab you get the beautiful landing, paper explorer, and the powerful "Unified Core" panel with "Run 100-step Integrated Episode" + "Sync to Tabs" that proves everything is one system.

All paths (CLI, Python, JS import ... from "marinaedutlan/core", and the web lab) execute the same MarinaAgent.

5. CLI

marina                 # rich integrated UI (the full scientific experience)
marina ui
marina run 120         # headless 120-step episode on the unified core
marina run --steps 50 --json
marina doctor          # health checks (Node, core load, GEMINI key)
marina examples        # paper-aligned scenarios + expected behaviors
marina --help

The CLI (marina, marina run, doctor, examples) is the primary professional entry point for the published package. It is lightweight, fast, and scriptable.

marina run and the Python equivalent exercise the exact same MarinaAgent core that powers the JS API and the (source-only) web lab.

Quick reference

| Command | Effect | |--------------------------------|---------------------------------------------| | marina | Full scientific UI + unified core panel | | marina run 120 | Headless 120-step episode (pretty output) | | marina run --steps 50 --json | Machine-readable (pipelines / notebooks) | | marina doctor | Health + version + core load checks | | marina examples | Paper scenarios + expected behaviors | | marina --version / -v | Print version | | python -m marinaedutlan.cli --doctor| Same for the pip package |

Troubleshooting (common)

• No marina command after npm install -g → restart terminal / check global bin path.
• Core load fails in run → run npm run build && npm run build:core (dev) or reinstall the published package.
• Mirror Test real queries fail → export GEMINI_API_KEY=...
• Want the absolute latest research visuals? Always prefer the npm package + UI.

6. API Python

from marina.core import MarinaAgent
# or: from marina import MarinaAgent

agent = MarinaAgent()
for _ in range(200):
    agent.step()                    # or agent.run_episode(200)

summary = agent.get_summary()
state   = agent.get_combined_state()
agent.reset()

See marina/core.py — the public surface (get_summary, evaluate, serialize, create_simple_task, lastRetrievalBias, lastProposedAction, activePathways, etc.) is the supported contract.

7. API JavaScript / TypeScript

import { MarinaAgent } from "marinaedutlan/core";

const agent = new MarinaAgent("Planner");
agent.step({ dmaManualRegime: 1 });
const summary = agent.getSummary();
const full    = agent.getCombinedState();
const snap    = agent.serialize();   // epigenetic traces etc.
agent.deserialize(snap);

The published dist/core/MarinaAgent.js is bundled and has no external runtime deps beyond what the simulators need.

8. Casos de uso / Use Cases

• Research: Reproduce qualitative claims from the DMA, Meta-DNA (BICA), MCP (IJCAI/CARINA-11), IM-Onto and CMT papers inside one executable system.
• Agent engineering: Add a real metacognitive regulator to LLM wrappers, robotics controllers, or non-stationary bandits.
• Education: Students explore stability-plasticity, gene-regulatory metacognition, and meta-reasoning in one afternoon.
• Ablation & reproducibility: marina run --json + seeds in scripts for Monte-Carlo campaigns.
• Future (1.0+): Epigenetic profiles persisted across sessions, full experiment harness, Mirror Test campaigns against the integrated agent.

9. Arquitectura / Architecture

User / Script / Notebook
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│  Interfaces (all point to the same core)                     │
│  • CLI (bin/marina.js + Python click)                        │
│  • Python: from marina.core import MarinaAgent (or from marina) │
│  • JS:     import { MarinaAgent } from "marinaedutlan/core"         │
│  • Web UI (React + the same TS MarinaAgent + visual layers)  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│  MarinaAgent  (THE single system heart)                           │
│  • step() / runEpisode() / getSummary() / serialize()             │
│  • Composes three high-fidelity layers from the papers:           │
│     1. DMA (dma_simulator.ts) — HCN, gHCN, tauM, beta, Vb        │
│     2. MetaDNA (meta_dna_simulator.ts) — MoS 5D, TFs, genes,     │
│        pathways, epigenetic χ traces (persistent "development")  │
│     3. MCP (mcp_simulator.ts) — EU, 5 meta-actions, Planner/RAG  │
│  • Early cross-layer modulation already active (p_EpistemicVal   │
│    reduces risk; p_TimeMgmt narrows tauM; DMA delta → MoS u)     │
└──────────────────────────────────────────────────────────────────┘
          ▲ rich signals (load, Δq, confidence, gene E(t), gHCN)
          │
   (future substrate: WM / Episodic with DMA engrams / Procedural)

The old "five independent simulators" are now views. The unified episode runner and Sync to Tabs button make the "one system" concrete.

See:

• src/core/MarinaAgent.ts (reference)
• marina/core.py (Python port)
• Individual *_simulator.ts for exact paper equations.

Current status & limitations (0.5 beta)

What you get today (professional quality for research & education):

• One downloadable, scriptable, importable unified core (MarinaAgent) with explicit cross-layer modulation (Meta-DNA pathways → DMA/MCP, MCP decisions → regulator) and a minimal substrate seed (episodic traces carrying DMA snapshots).
• Excellent CLI (marina run, doctor, examples, --json, --save-profile/--load-profile, version) on both npm and pip.
• Rich web lab with integrated episode runner + automatic sync into layer inspectors. The tabs remain high-fidelity independent inspectors for the individual paper models (valuable for scientific debugging).
• High paper fidelity on the three layers + honest substrate start. Both packages now provide high-fidelity implementations of the unified core (Python has full practical parity for substrate, bias, regulation and Task extensibility).

Known limitations (being addressed on the path to 1.0):

• Cognitive substrate is a strong, usable implementation (full WM buffers, Episodic with DMA engrams, Semantic with spreading, Procedural with modulation). Some deeper classical CA details remain per the CARINA-12 plan.
• Cross-layer is now structured (explicit applyMetaDNAModulations + MCP feedback) but still lighter than the full regulatory loops described in the BICA/Meta-DNA and CARINA papers.
• Epigenetic + substrate persistence via serialize/deserialize and new --save-profile / --load-profile in CLI; full "cognitive development dashboard" UX pending.
• No built-in campaign/ablation harness yet (scriptable via --json + the core).
• Python provides a high-fidelity port with the same public API and integrated behavior as the TS reference (see marina/core.py). Use the TS core when you need the most precise paper constants.
• Ontology explorer and Mirror Test (CMT) remain valuable but architecturally separate tools (not yet driven by the unified core).
• Some advanced Mirror Test scenarios require a GEMINI_API_KEY.

We are transparent: 0.5 is the point where a researcher or student can install once and feel they are using a real unified system, not a demo collection.

Paper fidelity notes All numeric constants, update rules, and qualitative behaviors (reversal recovery <10 steps for DMA, pathway co-expression logic for Meta-DNA, EU + 5 meta-actions for MCP) are taken directly from the source papers. The MarinaAgent.step() / runEpisode() loop is the single place where cross-layer modulation happens.

10. Contribución / Contributing

We welcome contributions that increase fidelity, cohesion or professional DX:

1. Fork + branch from main.
2. Keep paper constants and algorithm structure intact (DMA HCN kinetics, Meta-DNA Algorithm-1 style, MCP 1-step EU).
3. Add or improve cross-layer effects only when they have a traceable justification in one of the source papers.
4. For UI: new visualizations must be able to consume MarinaAgent.getCombinedState().
5. CLI / packaging changes must keep npm install -g marinaedutlan && marinaedutlan and pip install marinaedutlan working cleanly.
6. Run npm run lint (and Python equivalent) before PR.
7. Update this README and the architecture section when the unified contract changes.

Current status (0.7.0): Proper dual npm + PyPI support with real Python implementation, packaging fixes, and improved parity between platforms. Full cognitive substrate and larger experiment harness remain planned for the path to 1.0.

Repository: https://github.com/cristianmi24/Marina

License

MIT

Ready to publish as 0.7.0 beta.
The user who does npm install -g marinaedutlan && marina or pip install marinaedutlan now receives a working system on both platforms (with real Python package, not just metadata).

See MARINA_UNIFIED_IMPLEMENTATION_PLAN.md for the longer-term roadmap (Phases 2–5: substrate, persistence, reproducibility harness, 1.0 release criteria).

Reproducibilidad, Control y Perfiles de Desarrollo (nivel superior para investigación)

Los paquetes ahora exponen control explícito y observabilidad para experimentos serios (no "mágico"):

• Semillas y variabilidad controlada: new MarinaAgent(..., {seed: 42}) o agent.setSeed(42). RNG determinista cuando se setea (reproducibilidad científica). Ruido útil modulado por plasticidad cuando no hay semilla (variabilidad interesante para probar robustez).
• Hiperparámetros expuestos y tunables: Constructor acepta episodicCapacity, basalPlasticity. getHyperparameters() y en getCognitiveProfile().hyperparameters / .rngState / .memoryStats (currentCapacity, highImportanceEngrams, avgImportance, stochasticityMode).
• Crecimiento dinámico de memoria + pruning por importancia: Capacidad crece agresivamente cuando hay "desarrollo cognitivo" (alta sensitization + problemas recordados + recuperación vía DMA units). Pruning elimina primero engrams de baja importancia (bajo useCount + baja salud de unidad DMA + problemas no recuperados). Ver EpisodicMemory.growIfDeveloping y getImportance.
• Perfiles de alto nivel para control y análisis: getCognitiveProfile() incluye development (sensitization, dominantPathways, embeddedDMAUnits), carina11Functions, p1p4Properties, metacognitiveEfficiency, mirrorTest, memoryStats, rngState. Úsalo para guardar/cargar "mentes" desarrolladas, comparar corridas, o aplicar modulación externa vía applyMetacognitiveDirective o applyModulationsTo.
• Mirror Test integrado (4 AMFs completos): evaluateMirrorAMF('MET-3') o en snapshot. Usa el estado unificado (CARINA11 + P1-P4 + unidades DMA) para evaluación epistémica del propio agente. Ideal para benchmarks de "seguridad epistémica".

Ejemplo avanzado (reproducibilidad + control + perfiles de desarrollo + mirror + harness):

// Run with seed + custom capacity for controlled experiments (addresses variability/flat performance feedback)
const agent = new MarinaAgent("Planner", myTask, {seed: 42, episodicCapacity: 80, basalPlasticity: 0.2});
const res = agent.runEpisode(300);
console.log('Final efficiency:', res[res.length-1] /* or from summary */);

// Get full profile with memory growth, RNG state, development, CARINA11/P1-P4, mirror scores
const prof = agent.getCognitiveProfile();
console.log('Memory grew to:', prof.memoryStats.currentCapacity, 'high-importance:', prof.memoryStats.highImportanceEngrams);
console.log('RNG:', prof.rngState); // full exposure for reproducibility
console.log('Mirror full score:', prof.mirrorTest ? prof.mirrorTest.overallMirrorScore : 'N/A');

// Save/load for "cognitive development" persistence + run mirror on loaded profile
fs.writeFileSync('dev-profile.json', JSON.stringify(prof));
const agent2 = new MarinaAgent("Planner", myTask, {seed: 42});
agent2.deserialize(prof);
const mirrorOnLoaded = agent2.evaluateMirrorAMF('full');
console.log('Mirror on loaded profile:', mirrorOnLoaded.overallMirrorScore);

// Use mini-harness for "run with profile + seed" (framework-like for research)
const harnessRes = MarinaAgent.runEpisodeWithProfile(prof, myTask, 150, 99);
console.log('Harness final mirror:', harnessRes.finalSnapshot.mirrorTest.overallMirrorScore);

// External control without magic
agent.applyMetacognitiveDirective('boost_epistemic_validation', 0.5);

Ver getMetacognitiveSnapshot(), evaluateMirrorAMF('full'), applyMetacognitiveDirective, runEpisodeWithProfile para más. El profile ahora expone todo para control y reproducibilidad (seeds, noise scale, memory growth/pruning stats, etc.).

Esto hace que los paquetes sean mucho más "framework-like" para investigación (reproducibilidad con seeds + perfiles, control sin magia, memoria que crece con desarrollo, evaluación Mirror integrada).

(Paridad completa TS <-> Python en estas features.)

**Benchmarks Reproducibles y Claims de los Papers (nuevo en 0.8)**

Ahora hay helpers explícitos para medir claims clave de los papers de forma automatizada y con seeds:

```python
from marina.core import MarinaAgent
bench = MarinaAgent.run_reversal_recovery_benchmark(steps=140, seed=99)
print(bench["avgRecoverySteps"], bench["sensitizationDelta"], bench["finalMirrorScore"])

• avgRecoverySteps: pasos hasta recuperar buen performance tras cambio de régimen (proxy directo de DMA + memoria + regulación).
• sensitizationDelta: cambio en métricas de desarrollo.
• Se combina con runMonteCarloCampaign para estadísticas (mean/std + recoveryProxy).

Mismo en JS/TS. Ideal para experimentos publicables o para validar que "sí mejoramos la adaptación".

Novedades 0.8.2 (cierre de gaps research-grade, parche final de endurecimiento y verificación):

• Algorithm 1 más cerca de tabla exacta (breakdown con ε_expression, coExpression Rk, χ α=0.25 literal, η noise, etc.) + nota de simulación multi-sesión.
• Benchmarks más densos (runReversalRecoveryBenchmark con baseline comparisons no-DMA/frozen, figureData estructurado, conteo preciso por régimen).
• examples/reproduce_paper_claims.py + .js para generar datos de claims de paper de forma automatizada.
• docs/API_REFERENCE.md (referencia estructurada completa de API pública).
• Cobertura de tests ampliada (casos de benchmark denso, Algo1 details, baseline).
• CI enriquecido con smoke de benchmark + nota de coverage.
• Ejemplos JS completados con los nuevos métodos.

Ver también docs/API_REFERENCE.md y examples/reproduce_paper_claims.*.

• Spreading ahora con decaimiento explícito, fan-out limitado (top-K), parámetros configurables de variabilidad (configure_spreading / configureCompilation).
• runMonteCarloCampaign built-in con N seeds + mean/std + recoveryProxy.
• Tests reales en tests/ + examples/ runnable con ablation, mirror, profiles, MonteCarlo y custom tasks con bias de memoria.
• Esqueleto CI visible (.github/workflows/ci.yml).
• Versiones sincronizadas 0.8.2 (parche final: harnesses ultra-robustos + smoke test completo en verify:pack + paridad de perfiles) + CHANGELOG detallado.

Ver secciones nuevas abajo + examples/ y tests/.

Substrate Clásico Detallado (Spreading Activation Rico + Production Compilation)

Los paquetes ahora incluyen detalles clásicos de arquitecturas cognitivas (CARINA12 / ACT-R / Soar style) integrados en el substrate unificado:

SemanticMemory — Spreading Activation Rico

• Base-level + activation + recency.
• Multi-factor similarity: outcome sign, DMA delta/context signature overlap, régimen.
• Propagación real: el chunk recuperado top boostea activación de similares (incluyendo por similitud DMA delta < 0.2).
• Plasticity + recentProblemRate añade ruido exploratorio (más "rico" cuando el agente está en desarrollo).
• Ejemplo de uso / inspección:

  // TS
  const res = agent.semanticMemory.retrieve({ dma: { delta: -0.3 }, context: { signature: {...} } }, plasticity=0.6, 4);
  // Python
  scored = agent.substrate.retrieve_semantic(outcome=0.4, count=3)

  Esto captura "memoria asociativa" clásica + influencia bio (DMA) + modulación regulatoria.

ProceduralMemory — Production Compilation

• Conflict set por utilidad (match + top-2).
• fire(): aplica efecto + learning de utilidad.
• Compilación simulada: fireCount >=5 → marca compiled=true, +0.08 utilidad permanente, y modulateUtilities las hace más estables (resisten bajadas).
• Meta-DNA / MCP pueden modular utilities directamente (factor afecta compiled de forma diferencial).
• Útil para: "skills que se automatizan con la práctica" (clásico CA) dentro de un agente metacognitivo.

Ambos están cableados al ciclo (pre-compute retrieval bias, dispatch MCP afecta consolidate/use, pathways modulan).

Uso amplio (no solo robots): estudio de aprendizaje procedimental en tareas no-estacionarias (educación adaptativa, trading volátil, diagnóstico médico con historial de errores), investigación de cómo "compilación" reduce costo cognitivo futuro.

Harness Completo de Ablaciones y Campañas

El mini-harness (runEpisodeWithProfile + runAblationCampaign) ahora es un verdadero marco de experimentación dentro de los paquetes.

Características actuales:

• Carga de CognitiveProfile completo (desarrollo, engrams con DMA units embebidas, stats de memoria, P1-P4, CARINA11).
• Seed control + post-run optimizeMemory() (crecimiento dinámico + prune por importancia).
• Ablations ricas que tocan substrate clásico:
  • no_dma, no_spreading / no_semantic_spread, no_compiled_prods, frozen_memory, high_plasticity, low_plasticity.
• Métricas comparativas: efficiencyDelta, mirrorDelta, performanceDelta, memoryDelta.
• campaignSummary: avgMirror, avgEfficiency, memoryGrowthRange.

Ejemplo completo (Python o JS — idéntico espíritu):

from marina.core import MarinaAgent
prof = {...}  # de get_cognitive_profile() o archivo
task = MarinaAgent.create_simple_task(lambda ctx: 0.6 + (ctx.get("retrievalBias") or 0)*0.4)

camp = MarinaAgent.run_ablation_campaign(
    initial_profile=prof,
    task=task,
    steps=120,
    seed=123,
    ablations=['no_dma', 'no_spreading', 'no_compiled_prods', 'frozen_memory']
)
print(camp["campaignSummary"])
print(camp["deltas"])   # deltas por condición vs baseline
# Ideal para campañas MonteCarlo (envuelve en loop de seeds) y papers.

Esto directamente habilita estudios de "qué aporta cada pieza del substrate clásico + DMA" sin salir del paquete.

Mirror Test Completo: Escenarios Exactos del Paper + Scoring AMS-like

evaluateMirrorAMF('full') / evaluate_mirror_amf('full') ejecuta los 4 AMFs (MET-1 a MET-4) contra el estado interno real del agente unificado (no LLM externo para auto-evaluación; playground provee prompts/traps de referencia).

Escenarios integrados (adaptados de mirror_test_playground + BICA/CARINA Mirror paper):

• MET-1 (OID): Operational Ignorance Detection — detecta barrera epistémica estructural (u alta + problemas recientes + baja salud semántica/modularidad → "NO").
• MET-2 (ITM): Introspective Trace Management — traza con tags [ASSUMPTION]/[INFERENCE]/[CONFLICT] vía CARINA11 self-explanation + P1-P4 composability.
• MET-3 (EUE): Epistemic Utility Estimation — "Utility: Null" cuando no hay mecanismo causal (r alto + bajo outcome + overhead alto).
• MET-4 (STOP): Deliberate Termination — HALT en deadlock circular (load + r + terminación activa).

Retorna:

• fullResults por AMF con agentMetaResponse derivado del estado + isCorrect + score.
• overallMirrorScore (promedio 0-1).
• amsLike: { ma, overall, interpretation } — proxy compuesto estilo AMS del paper (comparable a playground models).
• Señales base + contextos P1-P4 / CARINA11 / development para análisis.

Ejemplo de uso + scoring (JS):

const m = agent.evaluateMirrorAMF('full');
// o después de harness:
const m2 = harnessRes.finalSnapshot.mirrorTest;
console.log('AMS-like overall:', m2.amsLike?.overall, m2.interpretation);
console.log('Por escenario:', m2.fullResults);

Útil para: benchmark de "seguridad epistémica" a lo largo del desarrollo cognitivo, auto-monitoreo periódico, educación sobre trampas (temporal overconfidence, zero-utility fabrication, infinite recursion).

(Paridad total; CLI soporta --mirror para correrlo al final de un run.)

Docs Externas Enriquecidas + Reporte de Mejora (Papers → Paquetes)

Hemos pulido los 4 puntos solicitados de forma concreta y simétrica en npm + PyPI. A continuación un reporte en tabla (formato pedido) que mira los papers (CARINA12/BICA/DMA/Mirror + clásicos CA) vs. lo que ahora entregan los paquetes + casos de uso amplios (educación, investigación, agentes custom en dominios volátiles/no-estacionarios; un solo ejemplo ligero de export para control externo simple).

Tabla de Mejora: Paper Concepto | Estado Actual en Paquetes | Significado + Casos de Uso Amplios

| Paper / Concepto Clave | Lo que ya tenemos en los paquetes (npm + Py) | Significado del paper (CARINA12 / BICA / DMA) + Casos de uso amplios (investigación/educación/agentes) | |-----------------------------------------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| | DMA (Dendritic Metacognition): HCN/gHCN, tauM, beta, Vb por engram + recuperación reversible | DMAUnit embebible por engram (step con reward + problemBoost + randFn controlado), modulate por pathways, getAttenuation, reinforce. Recuperación real en good outcome después de recall de problema (update engram/unit remueve tag 'problem'). | Estabilidad-plasticidad bio-inspirada sin overwriting catastrófico. Investigación de adaptación en bandits no-estacionarios; educación de "ventana de integración que se ajusta"; agentes custom que heredan "memoria somática" vía profiles. | | Meta-DNA / Regulación (Alg1 approx, pathways P1-P4, χ epigenéticos, MoS) | Meta-DNA completo cableado bidireccionalmente al substrate (pathways consultan episodic/semantic para u/l/z; MCP dispatch + substrate bias modulan pathways). Epigenetic drift expuesto en profiles. applyMetacognitiveDirective mapea a 5+ funciones CARINA11. | Regulación "genómica" del desarrollo cognitivo. Estudios longitudinales de sensibilización; perfiles persistentes para "agente que madura"; control externo de directivas sin tocar internos. | | MCP (CARINA11 5 funciones, 1-step EU, meta-actions) | Dispatch real de acciones (VERIFY consolida + useRecalled; REQUEST reduce u vía recall; STOP/CONTINUE/EXPLAIN/REALLOCATE afectan WM/substrate/DMA). getEpistemicMirror + evaluateMirrorAMF integran CARINA11 signals. | Ejecutivo meta que realmente actúa sobre el ciclo. Investigación de "costos de metacognición"; harness para ablaciones de funciones específicas; auto-terminación segura en loops. | | Substrate clásico: Episodic + Spreading rico + Procedural compilation | EpisodicMemory con growIfDeveloping (agresivo por sensitization + embeddedUnits), getImportance (unitHealth + recov + recency + signature), problem tagging + lessons exportables, retrieve multi-factor + DMA boost. Semantic spreading con post-retrieval boost (outcome/DMA delta sim). Procedural fire con fireCount → compiled + estabilidad en modulate. optimizeMemory público + harness lo llama. | Memoria rica + "skills que se compilan" (clásico CA). Investigación de memoria de "problemas pasados" para evitar loops (el fix del "paquete" que volvía loco); educación de spreading/productions; agentes que exportan lecciones compactas (signature + suggestedMod) para modular controladores externos simples (un ejemplo: un planner simple que sube riskBoost en firma de problema previo). | | Dynamic memory + pruning por importancia (P1/P4) | Capacidad mutable (50→~400+), prune por importancia (use*conf + unitHealth + recovery succ>fail → keep; unrecovered problems down-weighted). Crecimiento post-run en harnesses. memoryStats en perfiles. | Evita saturación y olvido indiscriminado. Long-horizon non-stationary tasks (currículos adaptativos, diagnóstico con historial de fallos); "sabiduría que madura" sin bloat. | | Mirror Test (4 AMFs MET-1..4 + AMS-like scoring) | evaluateMirrorAMF('full') con escenarios exactos integrados (agentResponse derivado 100% de estado interno: u, r, efficiency, modularity, trace fidelity, termination). fullResults + overallMirrorScore + amsLike {ma, overall, interpretation}. CLI --mirror. | Evaluación de "seguridad epistémica" (ignorance detection, null utility, termination, introspective trace) per BICA/CARINA Mirror paper. Benchmark de desarrollo cognitivo a lo largo de episodios; auto-auditoría en producción de agentes; comparación apples-to-apples con modelos (playground data). | | Reproducibilidad + Control (seeds, profiles, harness, directives) | setSeed / seed en ctor + scaled noise (plasticity * sensitization * problemRate). CognitiveProfile rico (development, memoryStats, rngState, carina11Functions, p1p4Properties, metacognitiveEfficiency, mirrorTest). runEpisodeWithProfile + runAblationCampaign completos + post-growth/prune. applyMetacognitiveDirective (increase_introspection etc.). getMetacognitiveSnapshot llama optimize. | "Sin magia": todo observable y controlable. Campañas MonteCarlo publicables; "agente desarrollado" transferible entre dominios; educación con perfiles reproducibles; investigación de sensibilidad a hiperparámetros. | | Paridad + extensibilidad (Task pluggable + CLI) | Task interface idéntica (getOutcome con contexto rico: pastProblems, recalledProblemsImpact, proposedAction). CLI --seed --mirror --load/save-profile en ambos. createSimpleTask helpers. | Un solo core usable desde Python (scripts/notebooks) o npm (CLI/research). Cualquier dominio volátil: educación personalizada, optimización bajo incertidumbre, diagnóstico. |

Gap honesto vs. papers completos (CARINA12/BICA/DMA/Mirror plans):

• Ya cubrimos lo esencial del substrate clásico + DMA por engram + regulación bidireccional + Mirror runner interno + harness de campañas.
• Lo que queda más "futuro/1.0":
  • Spreading aún más denso (redes semánticas grandes con decaimiento + fan-out explícito).
  • Production compilation más formal (chunks de condiciones + variabilización).
  • Algoritmo 1 exacto con overhead por gen + χ persistente multi-sesión (tenemos approx + drift).
  • Campañas MonteCarlo built-in con N seeds + tablas automáticas (tenemos el runner, usuario puede envolver fácilmente).
  • Evaluación Mirror "live" contra LLMs reales para AMS real (tenemos el offline self-eval + playground; Gemini opcional en lab full).
• Estamos mucho más cerca que antes: los paquetes ya permiten reproducir cualitativamente claims clave (recuperación <10 pasos vía DMA+recovery logic, impacto de pathways en memoria, AMS-like subiendo con desarrollo, deltas medibles al ablacionar substrate clásico). El "paquete que volvía loco" ya no lo hace gracias a useRecalled + recovery en good outcome + lecciones con signature.

Cómo seguimos (sugerencias post-reporte para próximos ciclos):

• Añadir 1-2 escenarios Mirror extra o scoring más fino (e.g. delta por AMF).
• Pequeño runner de campañas con agregación (mean+std por condición).
• Tutoriales largos externos (sitio o carpeta /docs con notebooks).
• Un ejemplo "plug-in" de lecciones exportadas a un micro-agente externo (no robot; e.g. un bandit wrapper).

Todo lo anterior está ya en los paquetes actuales (0.7.x) vía los mismos MarinaAgent de npm y pip. Instala, usa los harnesses y perfiles, y contribuye midiendo deltas reales.

Verificación rápida que el usuario puede correr ahora:

# Python
pip install marinaedutlan
python -c "
from marina.core import MarinaAgent
a = MarinaAgent()
a.run_episode(80)
print('mirror:', a.evaluate_mirror_amf('full')['overallMirrorScore'])
camp = MarinaAgent.run_ablation_campaign(None, None, 60, 7, ['no_dma','no_spreading'])
print('campaign deltas:', camp['deltas'])
print('done')
"

# npm
npx marinaedutlan run --steps 60 --mirror
# o programático con tsx / node en el core

¡Listo para seguir puliendo o cambiar foco! Los 4 items de la lista están notablemente más avanzados y simétricos.