CortexCore

0.1.6 verified Sat May 09 auth: no python

CortexCore is a modular library for building recurrent backbones and agent memory systems. It provides building blocks for stateful neural architectures, including LSTM, GRU, and attention-based memory modules, with a focus on composability and runtime efficiency. The current version is 0.1.6, targeting Python >= 3.12, with a monthly release cadence.

pip install cortexcore

Common errors

error ModuleNotFoundError: No module named 'cortex' ↓

cause Trying to import 'cortex' instead of 'cortexcore'.

fix

Install and import cortexcore: pip install cortexcore then import cortexcore.

error AttributeError: module 'cortexcore' has no attribute 'CortexBase' ↓

cause CortexBase is not a top-level attribute; it must be imported explicitly.

fix

Use from cortexcore import CortexBase.

error TypeError: CortexBase.__init__() got multiple values for argument 'stateful' ↓

cause Passing 'stateful' as a positional argument and keyword argument simultaneously.

fix

Ensure 'stateful' is passed only as a keyword argument: CortexBase(cell, stateful=True).

Warnings

breaking In version 0.1.6, the 'stateful' parameter of CortexBase must be passed as a keyword argument; positional usage is removed. ↓

fix Use `CortexBase(cell, stateful=True)` instead of `CortexBase(cell, True)`.

gotcha The package name is 'cortexcore' on PyPI, but the GitHub repository is under the 'metta' monorepo. Ensure you use 'cortexcore' in pip install, not 'metta-cortex'. ↓

fix Run `pip install cortexcore`.

deprecated The alias 'CortexCore' (CamelCase) for the module is deprecated in favor of 'cortexcore' (all lowercase). ↓

fix Use `import cortexcore` instead of `import CortexCore`.

gotcha When using stateful mode, you must manually call `reset_state()` before processing a new independent sequence, otherwise the hidden state carries over. ↓

fix Always call `model.reset_state()` before a new sequence when `stateful=True`.

Imports

CortexBase
wrong
```
from cortex import CortexBase
```
correct
```
from cortexcore import CortexBase
```
The top-level package is 'cortexcore', not 'cortex'.

LSTMCell

wrong

from cortexcore import LSTMCell

correct

from cortexcore.cells import LSTMCell

Cell implementations are in the submodule 'cells'.

MemoryModule

wrong

from cortexcore import MemoryModule

correct

from cortexcore.memory import MemoryModule

Memory modules are in the submodule 'memory'.

Quickstart

Minimal example creating a recurrent backbone using an LSTM cell and processing a sequence.

import torch
from cortexcore import CortexBase
from cortexcore.cells import LSTMCell

# Create a simple recurrent backbone
cell = LSTMCell(input_size=10, hidden_size=20)
base = CortexBase(cell, stateful=True)

# Process a sequence
x = torch.randn(5, 10)  # sequence length 5, batch size 1
output, hidden = base(x)
print(output.shape)  # torch.Size([5, 20])

# Reset state for new sequence
base.reset_state()