Metadata-Version: 2.4
Name: elume
Version: 0.1.0
Summary: Elume — an open-source agentic memory engine for long-horizon adaptive learning. An integration layer bringing together LinOSS oscillatory state-space models, attractor-based associative memory, and MemEvolve-style adaptive memory mechanisms into a single unified memory kernel. The contribution is integration, not invention.
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: Mani Saint-Victor
License: MIT
License-File: LICENSE
Keywords: active-inference,attractor-basins,linoss,memory,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: numpy>=1.26
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)

**An open-source agentic memory engine for long-horizon adaptive learning.**

Elume brings together existing memory and sequence-modeling components into a single working system for long-horizon agents.

It integrates LinOSS-style long-horizon temporal encoding (Rusch & Rus, ICLR 2025), attractor-based associative memory, and MemEvolve-style adaptive memory mechanisms (Zhang et al., arXiv:2512.18746, 2025) into one open-source stack. The contribution of Elume is not the invention of these underlying methods in isolation, but the engineering work required to combine them, adapt their codepaths, and make them operate coherently in a unified memory system.

## What Elume is

Elume is an integration layer and runtime memory stack for agents that need to:

- encode long trajectories,
- recover useful prior state through associative recall,
- and adapt memory behavior over time.

In practice, Elume packages and stabilizes multiple upstream ideas and implementations so they can be used together as a single agent memory engine.

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

## Core composition

Elume combines:

1. **LinOSS-based temporal encoding** for long-horizon trajectory representation.
2. **Attractor-based associative memory** for content-addressable recall.
3. **MemEvolve-style adaptive memory logic** for improving memory behavior over time.

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

## 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. Methodology for adaptive evolution of memory retrieval and management strategies.
- **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.

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-one 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, and prior-gated cognition. Track `007` was retired after source review showed it was framed against the wrong dionysus3 concept. **1041 tests passing, ruff clean.**

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

Archon-style deterministic-harness adoption is staged on `feat/archon-readiness-phase-1`. The kernel has injected RNGs, frozen trajectory metadata, provider snapshots, and an `elume.envelope` v0 operation registry covering belief embedding, evolution step, thought competition, self-model stepping, and Hopfield recall. The remaining design question is cross-platform float-hash policy.

## Install

Requires Python `>=3.11`.

```bash
pip install elume
```

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

## 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
│       └── 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.1.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 — Evolving, Long-horizon, Unified, Memory, Engine.

For public descriptors:
- **Short:** *Agentic Memory Engine*
- **Technical long form:** *Long-Horizon Adaptive Memory Engine*
- **Tagline:** *An open-source agentic memory engine for long-horizon adaptive learning.*

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