Cognitive Substrate Incubator

Modular cognition primitives for long-running AI agents.

This repo is an incubator for cognition packages used by autonomous LLM agents. Each package ships alone with its own academic-citation backbone. Companion to elume, which provides the memory layer.

Status

Pre-release. No packages have shipped yet. This README documents intent and scope. Each package will become its own publishable PyPI artifact (and, eventually, its own dedicated repository) once its boundary is proven inside the incubator.

Why an incubator

Many memory and cognition components are strong in isolation but difficult to combine. This repo is an incubator workspace where we extract candidate packages, prove their boundaries, run consumer tests, and only graduate them to standalone repositories when each package has stable APIs, tests, docs, and clear external identity.

This avoids the failure mode where a dozen empty repositories created on day one end up with governance overhead and a fragmented appearance before any package has earned its independence.

Planned packages

Each package adopts alone. Each has a clean academic-citation story.

Package	Role	Foundational citations
active-inference-records	Foundational state types (ActiveInferenceState, EFE/VFE, precision facets)	Friston Active Inference (MIT 2022), Tal et al. 2026
meta-tot	Active-inference-scored Tree of Thought reasoning	Yao 2023 (ToT), Friston 2022, Treur 2016, Tal et al. 2026, Bernstein et al. 2015
agentic-substrate (name TBD)	ThoughtSeed + ThoughtLayer + MarkovBlanket + NeuronalPacket + MetacognitiveParticle + competition mechanism	Laukkonen, Chandaria; Friston Markov Blanket
computational-phenomenology	Transparency/opacity, meta-awareness, identification, metacognitive feelings, Phenomenal Self-Model	Sandved-Smith et al. 2021, Metzinger 2003 Being No One
iwmt-workspace	Self-Organizing Harmonic Modes (SOHM), workspace ignition (alternative competition strategy)	Safron 2020 IWMT, Dehaene-Changeux 2011

Companion: elume

elume (https://github.com/bionicbutterfly13/elume) is the memory layer:

• LinOSS-based temporal encoding (Rusch & Rus, ICLR 2025)
• Attractor-based associative memory (Hopfield 1982, Context-Engineering)
• MemEvolve-style adaptive memory logic (Zhang et al. arXiv:2512.18746)
• Self-modeling networks (Treur 2016)

The packages in this incubator depend on elume where memory persistence or basin dynamics are needed. The dependency direction stays one-way: cognition imports memory, never the reverse.

Principles

• Integration, not invention. The underlying techniques are open source or openly published. Our work is bringing them together coherently and shipping them with attribution-clean provenance.
• Atomic adoption. Each package solves one concern and adopts alone. Users who want only meta-tot should not need to install everything.
• No framework lock-in. No FastAPI, no LangChain runtime, no agent-framework dependencies in core packages.
• Pluggable storage. Storage backends are protocols, not implementations.
• The past is frozen. Cognitive state records are immutable. Successor semantics for evolution.
• Citations in the kernel. Upstream foundations live in NOTICE and PROVENANCE.md; safe-claim language is enforced in CLAIMS.md.

Repository structure (planned)

cognitive-substrate-incubator/
├── packages/
│   ├── active-inference-records/
│   ├── meta-tot/
│   ├── agentic-substrate/        # name TBD
│   ├── computational-phenomenology/
│   └── iwmt-workspace/
├── adapters/                     # framework integrations (LangGraph, LlamaIndex, DSPy)
├── benches/
│   └── cognitive-bench/          # reproducible benchmarks
├── docs/
│   ├── governance.md
│   └── claim-language.md
└── scripts/
    └── ci/                       # forbidden-claim grep, attribution checks

License

Apache-2.0 by default. Patent-grant clause matters for cognitive-architecture defensibility.

Some packages may ship MIT (e.g., pure-math primitives where patent surface is negligible). License per-package is stated in each package's LICENSE file and pyproject.toml.

Source codebase

Every package in this incubator was originally developed inside dionysus3, a research cognitive architecture. Extraction follows two-fleet discipline (relocation vs rewrite) modeled on elume's process. Per-package provenance tracking documents what was relocated verbatim vs what was rewritten.

Getting involved

Pre-release. APIs not stable. If you want to use a package before its first PyPI release, fork at your own risk and expect breaking changes.

Once a package reaches v0.1.0 with working CI, tests, examples, and a published PROVENANCE.md + CLAIMS.md, it will be announced here and on PyPI.