# bimoh

Fractal plasticity regulator — entropy, information gain, and local complexity (`d_i`) update for artificial memory systems.

Each processing unit (memcon) has a parameter `d_i ∈ [0, 3]` representing its accumulated activation history and neighborhood influence:

| d_i range | State | Behavior |
|-----------|-------|----------|
| 0.0 – 0.4 | Inactive | No recent activation. Pruning candidate. |
| 0.4 – 1.5 | Specialized | Consolidated memory with specific context. |
| 1.5 – 3.0 | Integrator | High connectivity, multi-concept mixing. |

## Update function

```
d_i(t+1) = d_i(t) - λ(1 - a_i) + β(a_left + a_right)
```

Where:
- `λ` (lambda): decay rate per tick without activation. Typical: `0.015`
- `β` (beta): regeneration rate per active neighbor. Typical: `0.07`
- `a_i`: normalized activity of unit i, range [0, 1]
- `a_left`, `a_right`: activity of adjacent units in the mesh

Result is clamped to [0.0, 3.0].

## API

| Function | Input | Returns | Description |
|----------|-------|---------|-------------|
| `BimoH::new(threshold_ig, lambda, beta)` | 3 f32 params | `BimoH` | Create regulator with given plasticity parameters |
| `entropy(activities)` | `&[f32]` | `f32` | Shannon entropy of activation distribution. Maximum = log₂(n) for uniform distribution |
| `information_gain(before, after)` | f32, f32 | `f32` | Entropy reduction: `before - after` |
| `should_consolidate(ig)` | f32 | `bool` | `true` if information gain exceeds `threshold_ig` |
| `update_d_i(current, activity, neighbors)` | f32, f32, (f32,f32) | `f32` | Applies plasticity formula, clamps to [0, 3] |

## Usage

```rust
use bimoh::BimoH;

let b = BimoH::new(0.15, 0.015, 0.07); // threshold_ig, lambda, beta

// Update d_i with full activity + active neighbors → increases
let new_d = b.update_d_i(0.5, 1.0, (0.3, 0.2));
assert!(new_d > 0.5);

// No activity, no neighbors → decays
let inactive = b.update_d_i(0.5, 0.0, (0.0, 0.0));
assert!(inactive < 0.5);

// Shannon entropy of uniform distribution = log₂(4) = 2.0
let h = BimoH::entropy(&[1.0, 1.0, 1.0, 1.0]);
assert!((h - 2.0).abs() < 0.001);

// Information gain
let ig = b.information_gain(2.0, 1.0); // 1.0 bits gained
assert!(b.should_consolidate(ig));     // exceeds threshold 0.15
```

## Struct fields

```rust
pub struct BimoH {
    pub threshold_ig: f32,  // min information gain to consolidate (default: 0.15)
    pub lambda: f32,        // decay per tick without activation (default: 0.015)
    pub beta: f32,          // regeneration per active neighbor (default: 0.07)
}
```

## Data types

```rust
pub struct Memcon {
    pub id: u32,
    pub complexity: f32,  // d_i value
}
```

## Installation

```bash
cargo add bimoh
```

## Pipeline position

`bimoh` provides the plasticity mechanism in the [SHCortex](https://crates.io/crates/shcortex) artificial memory pipeline:

```
lnhash → malla_multi → [bimoh] → lcc → SQLite
```

Can be used independently in any system requiring dynamic importance regulation for processing units.

## License

MIT
