Metadata-Version: 2.4
Name: elume
Version: 0.5.0
Summary: Agentic memory with mental-model architecture. Deterministic, replay-safe substrate for cognitive-architecture agents: LinOSS temporal encoding, Hopfield attractor memory, mental-model and metacognitive primitives, strategy evolution, pluggable MemEvolve benchmark adapter. Contribution: byte-identical replay, immutable lineage, provider abstraction, composable operators.
Project-URL: Homepage, https://github.com/bionicbutterfly13/elume
Project-URL: Repository, https://github.com/bionicbutterfly13/elume
Project-URL: Issues, https://github.com/bionicbutterfly13/elume/issues
Project-URL: Changelog, https://github.com/bionicbutterfly13/elume/blob/main/CHANGELOG.md
Author-email: Mani Saint-Victor <drmani215@gmail.com>
License: MIT
License-File: LICENSE
Keywords: active-inference,attractor-basins,cognitive-architecture,deterministic,linoss,memory,mental-model,metacognition,self-evolving
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: linoss-dynamics<0.3,>=0.2.2
Requires-Dist: numpy>=1.26
Provides-Extra: active-inference
Requires-Dist: inferactively-pymdp<1.0,>=0.0.7.1; extra == 'active-inference'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Elume

[![PyPI version](https://img.shields.io/pypi/v/elume.svg)](https://pypi.org/project/elume/)
[![Python versions](https://img.shields.io/pypi/pyversions/elume.svg)](https://pypi.org/project/elume/)
[![CI](https://github.com/bionicbutterfly13/elume/actions/workflows/ci.yml/badge.svg)](https://github.com/bionicbutterfly13/elume/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Agentic memory with mental-model architecture — a deterministic,
replay-verifiable substrate for cognitive-architecture agents.**

Elume is the cognitive substrate underneath an agent: long-horizon temporal
encoding, attractor-based associative memory, mental-model primitives,
metacognitive control, and deterministic strategy evolution behind clean
provider boundaries. Registered envelope operations have a deterministic replay
contract; adapters outside that envelope have their own documented guarantees.

Memory is the entry point. Mental modeling is the architecture. Replay-safety is the engineering contribution.

It integrates LinOSS-style temporal encoding (Rusch & Rus, ICLR 2025), Hopfield-style associative memory, mental-model and metacognitive record types, and a deterministic evolution substrate into one open-source stack. The contribution of Elume is not the invention of the underlying methods in isolation, but the engineering work required to combine them, adapt their codepaths, and make them operate coherently inside a single deterministic kernel.

## What Elume is

Elume is a runtime cognitive substrate for agents that need to:

- encode long trajectories with oscillatory state-space dynamics,
- recover useful prior state through attractor-based associative recall,
- maintain explicit mental models with predictions and revisions,
- exercise metacognitive control over inference and action selection,
- and evolve memory strategies over time, deterministically.

The full primitive set:

| Layer | Modules | Role |
|---|---|---|
| **Temporal encoding** | `elume.linoss` | LinOSS solver, encoder, timing |
| **Memory substrate** | `elume.basins`, `elume.network` | Attractor field, Hopfield, self-modeling network |
| **Mental modeling** | `elume.models.mental_model`, `elume.cognition.mental_model` | `MentalModel`, `BasinRelationship`, `PredictionTemplate`, `ModelPrediction`, `ModelRevision`, mental-model subnetworks |
| **Metacognition** | `elume.models.metacognitive` | `CognitiveCore`, `MetacognitiveParticle`, `MentalAction`, `ParticleType` |
| **Belief & cognition** | `elume.models.belief`, `elume.models.cognitive`, `elume.cognition` | Belief states, cognitive events, deterministic thought competition, prior-gated cognition, curiosity homing |
| **Evolution** | `elume.evolution` | Strategy lifecycle, GA over immutable `Strategy` records |
| **Determinism** | `elume.envelope` | Canonical pre-image hashing, byte-identical replay |
| **Integration** | `elume.providers`, `elume.adapters`, `elume.embedders` | Provider contracts, MemEvolve cartridge, embedding protocols |

In practice, Elume packages and stabilizes multiple upstream ideas plus original cognitive-architecture engineering so they can be used together as one substrate.

## What Elume is not

Elume does not claim authorship of the original LinOSS, MemEvolve, or Hopfield-style memory ideas.

Instead, it is an open-source composition of these components, with the modifications, interfaces, and system-level fixes needed to make them work together in one usable framework.

Elume's evolution module is a deterministic genetic algorithm operating on
deeply immutable `Strategy` records through a provider boundary. When invoked
through the registered envelope operation, identical inputs on the witnessed
numeric platform produce the same replay hash. The framing — agent memory as
an evolvable population rather than policy weights — is adopted from MemEvolve
(Zhang et al. 2025, arXiv:2512.18746).

## What Elume created

Things that did not exist anywhere before this project:

- **The deterministic envelope** (`elume.envelope`, v0.1) — a canonical
  BLAKE2b-256 post-state pre-image over the result, output RNG state, output
  provider snapshot, platform tag, and numeric probe. Portable artifact v3
  records bind the complete input/output record with HMAC-SHA256 using a
  caller-supplied key of at least 32 bytes; the key is never stored in the
  artifact. Legacy v1/v2 artifacts remain readable but cannot pass authenticated
  integrity verification or local replay. Seven reference operations are
  registered today (belief embed,
  basin recall, thought competition, formal policy inference, evolution step,
  self-model step, curiosity score).
- **The platform-tagged float-hash policy** — `platform_fingerprint()`
  (arch, OS, interpreter, Python version, NumPy version) and a behavioral
  `numeric_backend_probe()` are folded into the canonical pre-image, so replay
  drift across coarse host fields or exercised numeric kernels surfaces as a
  localized hash mismatch (see
  [`docs/archon-readiness/21-float-hash-policy.md`](./docs/archon-readiness/21-float-hash-policy.md)).
- **`elume.adapters.memevolve.ElumeMemoryProvider`** (v0.2) — a deterministic
  MemEvolve-compatible provider adapter. Same seed and same call ordering
  produce equal provider responses for the tested in-process lifecycle on a
  fixed platform. The adapter path is not envelope-hashed and does not fold
  the platform fingerprint; only registered envelope ops carry that tag.
- **`cognition.curiosity_score`** as a replayable envelope op (v0.2) —
  Shannon-entropy + information-gain scoring wrapped with the same
  hash-equal replay contract as every other op. The math is ported
  from dionysus3 (credited below); the envelope wrap, the integration
  with `run_gated_thought_competition`, and the `CuriosityPrior`
  derivation are original Elume work.
- **Hyperevolution coupling** (v0.2) — the wiring inside
  `ElumeMemoryProvider` that lets curiosity continuously re-acquire
  the search heading: `provide_memory` re-ranks basins by current
  information gain; `take_in_memory` updates a per-session
  `BeliefBuffer` from trajectory outcomes; the whole pattern toggles
  via one config key.
- **The kernel discipline** — frozen records, successor semantics
  (`.evolved()`, `.revised()`, `.with_status()`), injected RNG,
  provider-boundary persistence, no framework dependencies. This
  discipline applied uniformly across LinOSS, basins, evolution,
  cognition, embedders, and providers is what makes the whole stack
  composable inside one Python package.

What Elume adopted from upstream is named in the [Attribution](#attribution)
section. What Elume created is everything in the bullets above.

## Core composition

Elume combines:

1. **LinOSS-based temporal encoding** for long-horizon trajectory representation.
2. **Attractor-based associative memory** for content-addressable recall.
3. **Deterministic adaptive memory logic** for improving memory behavior over time, with an optional curiosity homing signal.

These components are integrated into a shared memory pipeline for agentic learning.

## Why Elume

- **Determinism** — injected RNG and hash-equal replay for registered envelope
  operations within the witnessed platform/numeric contract.
- **Immutable records** — nested containers are recursively frozen and NumPy
  arrays use detached, byte-backed storage whose write lock cannot be
  re-enabled. Strategies evolve via successors, not mutation.
- **Provider boundary** — storage is a protocol contract, not an implementation. Swap backends without touching cognition code.
- **No framework lock-in** — no FastAPI, Graphiti, or agent runtime in the core. Adapters live in consumers.
- **Cross-platform float-hash policy** — `platform_fingerprint()` (arch, OS, interpreter, Python, NumPy version) is folded into the canonical hash pre-image, so drift across those dimensions surfaces as a hash mismatch. Same-fingerprint replay assumes the same numeric (BLAS) backend — see [the float-hash policy](./docs/archon-readiness/21-float-hash-policy.md).
- **Numeric-backend witness** — `numeric_backend_probe()` adds fixed float64 matmul, sum, fused ufunc, and dot-product bytes to the envelope pre-image. It does not prove all BLAS behavior, but drift in the exercised kernels localizes to the `numeric_probe` segment.
- **Curiosity-driven hyperevolution** — the optional curiosity homing signal biases memory retrieval toward entropy-reducing directions, adding a goal-directed retrieval signal.
- **Content-addressed replay artifacts** — provider snapshots can stay full dumps by default or emit a manifest/root-hash form for larger replay stores.

Elume uses "expected free energy" in two explicit places. `cognition.thought_competition` is the shipped heuristic score for ranking immutable thought candidates. `cognition.policy_inference` is the formal generative-model policy-inference envelope op backed by the optional `pymdp` adapter; it is separate from the thought-competition heuristic and is replay-hashed like every other operation.

## MemEvolve cartridge

Elume v0.2.0 ships a `BaseMemoryProvider`-compatible adapter so MemEvolve
([bingreeky/MemEvolve](https://github.com/bingreeky/MemEvolve)) can benchmark
Elume from a local checkout. Two-line registration, then:

```bash
python run_flash_searcher_mm_gaia.py --memory_provider elume --sample_num 5
```

See [docs/adapters/memevolve.md](./docs/adapters/memevolve.md) for the full
install guide, determinism guarantee, and hyperevolution mode.

## Why Elume exists

Many memory systems are strong in isolation but difficult to combine in practice.

Elume exists to make these components interoperable: to unify their interfaces, reconcile assumptions, patch incompatibilities, and provide a coherent open-source implementation that others can inspect, use, and build on.

## Attribution

Elume builds directly on upstream work and code associated with LinOSS, MemEvolve, Hopfield-style associative memory, and attractor / neural-field context-engineering ideas.

Specific upstream sources:

- **LinOSS — Oscillatory State-Space Models** — T. Konstantin Rusch and Daniela Rus, *International Conference on Learning Representations (ICLR)*, 2025. Temporal encoding substrate and oscillator dynamics inside the basin field.
- **MemEvolve — Meta-Evolution of Agent Memory Systems** — Guibin Zhang, Haotian Ren, Chong Zhan, Zhenhong Zhou, Junhao Wang, He Zhu, Wangchunshu Zhou, and Shuicheng Yan, arXiv preprint [2512.18746](https://arxiv.org/abs/2512.18746), 2025. Source of the evolvable-memory-population framing. The `BaseMemoryProvider` cartridge interface and shaping helpers in `src/elume/adapters/memevolve/shaping.py` are adapted from the [bingreeky/MemEvolve](https://github.com/bingreeky/MemEvolve) codebase (Apache-2.0), with HTTP/HMAC stripped.
- **Context Engineering: Beyond Prompt Engineering** — Context Engineering Contributors (maintained by David Kimai), [github.com/davidkimai/context-engineering](https://github.com/davidkimai/context-engineering) (MIT), 2025. Source of the attractor-based neural-field model at the core of Elume's memory layer — specifically `00_foundations/08_neural_fields_foundations.md`, `00_foundations/11_emergence_and_attractor_dynamics.md`, `40_reference/attractor_dynamics.md`, and the memory-attractor protocol shells in `60_protocols/shells/`.
- **Hopfield-style associative memory** — Hopfield (PNAS 1982); textbook synthesis from Anderson (2014, Ch. 13); capacity bound from Amit, Gutfreund & Sompolinsky (1985). Classical mathematical substrate for discrete pattern storage inside the basin subsystem.
- **Source codebase** — **dionysus3**, a research cognitive architecture. Every module in `elume/` was originally developed there. Elume relocates the kernel math with verbatim semantics and strips project-specific glue so the result is a pure library. The Shannon-entropy + information-gain mechanism in `src/elume/cognition/curiosity.py` is ported from dionysus3's `CuriosityDriveService` (`api/services/mosaeic_self_discovery.py` and `arousal_system_service.py`).

BibTeX entries for all upstream academic citations are in [`CITATIONS.bib`](./CITATIONS.bib). Please cite the upstream sources in any published work that uses Elume.

## Status

Elume is an open-source integration project under active development.

Twenty-six tracks landed: kernel bootstrap, core data models, LinOSS solver + timing, Hopfield network, basin field engine, attractor basin core, embedder protocol, provider contracts, the evolution engine, the self-modeling network engine, immutable cognitive record types, immutable mental-model domain records, immutable metacognitive control records, prior hierarchy records, mental-model subnetworks, the cognitive event protocol, cognitive-event embedders, immutable thought-level records, immutable neuronal-packet records, deterministic thought competition, prior-gated cognition, the MemEvolve cartridge, curiosity homing device, hyperevolution wiring, and content-addressed provider snapshots. Track `007` was retired after source review showed it was framed against the wrong dionysus3 concept. Ruff scope is `src`, `tests`, and `reference_service/src`.

Phase 2 is complete through the prior gate: `Track 011` shipped `elume.network`, `Tracks 014`, `016`, `018`, `021`, and `022` landed the minimal cognition gate from `MentalModel` through `LinOSSEncoder`, `Tracks 012`, `013`, and `019` landed immutable thought and packet records plus deterministic EFE competition, and `Tracks 015`, `017`, and `020` landed metacognitive control, generic priors, and prior-gated cognition. See [`conductor/tracks.md`](./conductor/tracks.md).

Phase 3 is complete: the MemEvolve cartridge (`elume.adapters.memevolve`), curiosity homing (`elume.cognition.curiosity`), and hyperevolution wiring now connect Elume's deterministic substrate to MemEvolve's outer evolutionary loop. Phase 4 has started with content-addressed provider snapshots for larger replay artifacts.

Archon-style deterministic-harness support is implemented in the kernel. Elume has injected RNGs, frozen trajectory metadata, provider snapshots, content-addressed snapshot manifests, and an `elume.envelope` v2 operation registry covering belief embedding, evolution step, thought competition, formal policy inference, self-model stepping, Hopfield recall, and curiosity scoring. Cross-platform float-hash policy is documented in `docs/archon-readiness/21-float-hash-policy.md`.

## Install

Requires Python `>=3.11`.

```bash
pip install elume
```

## Quickstart

The fastest way in is one complete cognitive cycle: an observation becomes a
decision, a later outcome updates the model, and the whole thing replays exactly
from an authenticated record. That flow lives in
[`docs/quickstart.md`](./docs/quickstart.md) and runs as a single script:

```bash
python examples/observation_driven_cycle.py
```

Install Elume `0.5.0` to run the cognitive-cycle quickstart:

```bash
pip install elume==0.5.0
```

### Also: deterministic strategy evolution

This shorter example shows the replay envelope on its own: a memory strategy can
change, and the change is still replayable. The same input produces the same
result and the same post-state hash, which gives you an audit trail for agent
memory instead of an opaque update.

Create `elume_quickstart.py`:

```python
from elume.envelope import replay
from elume.envelope.protocol import SCHEMA_VERSION, EnvelopeInput, Verdict
from elume.envelope.snapshot import serialize_strategies
from elume.models import Strategy


strategies = (
    Strategy(name="careful", genotype={"temperature": 0.2}, created_at=1.0),
    Strategy(name="balanced", genotype={"temperature": 0.6}, created_at=1.0),
    Strategy(name="bold", genotype={"temperature": 0.9}, created_at=1.0),
)

scenario = EnvelopeInput(
    schema_version=SCHEMA_VERSION,
    scenario_id="quickstart.evolution_step",
    run_id="run-1",
    seed=123,
    operation="evolution.step",
    operation_args={
        "fitness": {"careful": 0.2, "balanced": 0.8, "bold": 0.5},
        "elite_k": 1,
        "operator_config": {"kind": "jitter", "scale": 0.05},
    },
    provider_snapshot=serialize_strategies(strategies),
)

# Run the step twice and prove the same input yields the same replay hash.
outcome = replay("evolution.step", scenario, n=2)
first = outcome.outputs[0]

assert first.verdict is Verdict.PASS
assert outcome.matched

children = list(first.result["children"])
print("verdict:", first.verdict)
print("new children:", [child["name"] for child in children])
print("population:", first.result["population_ids"])
print("post-state hash:", outcome.hashes[0])
print("replay matched:", outcome.matched)
```

Run it:

```bash
python elume_quickstart.py
```

The important line is `replay matched: True`. Elume created new child memory
strategies, then proved that the same scenario can be replayed exactly.

For a fuller walkthrough, see [docs/quickstart.md](./docs/quickstart.md).

## Quickstart (development)

For local development, use [`uv`](https://github.com/astral-sh/uv) and an editable install:

```bash
# from the repo root
uv venv .venv
uv pip install -e ".[dev]"

# run the test suite
.venv/bin/pytest

# lint
.venv/bin/ruff check src tests reference_service/src

# optional: reference service demo
uv pip install -e ./reference_service
PYTHONPATH=src:reference_service/src python -m reference_service
```

### Spec-driven development

Elume uses [GitHub Spec Kit](https://github.com/github/spec-kit) with Codex skills. The
project constitution is [.specify/memory/constitution.md](./.specify/memory/constitution.md),
and active feature artifacts belong under `specs/`. Start a new feature with
`$speckit-specify`, then use `$speckit-clarify`, `$speckit-plan`, `$speckit-tasks`, and
`$speckit-implement` as appropriate. Dated pre-migration ideation reports are retained in
[`docs/planning-history/`](./docs/planning-history/) as historical evidence, not active work.

## Layout

```
elume/
├── src/
│   └── elume/
│       ├── basins/      # Hopfield + basin field dynamics (neural fields model)
│       ├── cognition/   # mental-model subnetworks + typed cognitive events
│       ├── embedders/   # event -> trajectory projection protocols
│       ├── linoss/      # oscillatory state-space primitives (solver, timing, encoder)
│       ├── network/     # self-modeling network substrate for Phase 2 cognition
│       ├── evolution/   # successor-based strategy evolution
│       ├── providers/   # storage contracts + reference provider
│       ├── envelope/    # deterministic replay envelope + reference ops
│       ├── adapters/    # provider adapters (memevolve cartridge)
        └── models/      # beliefs, strategies, trajectories, cognitive + thought records
├── reference_service/   # runnable CLI/FastAPI demo (separate package, optional)
├── tests/
│   ├── unit/            # unit tests for kernel modules
│   ├── contract/        # contract tests consumers re-run against their impls
│   └── integration/     # end-to-end composition tests across subsystems
└── conductor/           # spec-driven development docs and tracks
```

## Consuming Elume

Downstream projects pin a versioned PyPI release:

```bash
pip install elume==0.5.0
```

For co-development against an unreleased branch, an editable install also works:

```bash
# from the consumer repo (e.g. dionysus3)
pip install -e /path/to/elume
```

## Principles

- **Integration, not invention.** The underlying techniques are open source or openly published; Elume's work is bringing them together.
- **Kernel, not application.** Reusable mechanism only. Adapters and policies live in consumers.
- **No framework lock-in.** No FastAPI, no Graphiti, no agent runtime in the core.
- **Pluggable storage.** Providers are contracts, not implementations.
- **Reproducible.** Deterministic where possible; evolution randomness goes through an injectable RNG.
- **Contract tests as the regression net.** Consumers re-run `tests/contract/` against their provider implementations.
- **The past is frozen.** Trajectory records, belief snapshots, and basin activations are immutable. Strategies evolve by producing successors, not by mutating in place.

## On the name

**Elume** is the brand form. **ELUME** works as an acronym mnemonic — Evolvable Long-horizon Unified Mental-model Engine.

For public descriptors:
- **Short:** *Cognitive Substrate for Agents*
- **Memory-first framing (for SaaS/category fit):** *Agentic Memory with Mental-Model Architecture*
- **Technical long form:** *Deterministic, Replay-Safe Substrate for Cognitive-Architecture Agents*
- **Tagline:** *Agentic memory with mental-model architecture — a deterministic, replay-safe substrate for cognitive-architecture agents.*

## License

MIT. Compatible with Context-Engineering's MIT license and all upstream components.

See [`ATTRIBUTION.md`](./ATTRIBUTION.md) and [`conductor/product.md`](./conductor/product.md) for the full attribution and product specifications.
