Skip to content

SDK Sparse Event-Memory LM Guide

Purpose

This guide shows how to build SparseEventMemoryLM through the SDK, perform local learning, and send restartable artifacts to the API. The implementation is EvoSpikeNet-Core/evospikenet/sdk/sparse_event_memory.py.

This model is separate from the dense SpikingEvoTextLM / ChronoSpikeAttention path. Primary CSR synapses are INT8 buffers; Adam updates only the tied vocabulary basis, router, low-rank adapters, and normalization parameters.

Public SDK API

The following objects are directly importable from evospikenet.sdk.

API Purpose
SparseEventMemoryConfig Serializable configuration for the model and checkpoint
build_sparse_event_memory_model() Build a model from configuration and optionally move it to a device
create_sparse_event_memory_artifact_payload() Create in-memory state-dict, config.json, and memory_report.json payloads
upload_sparse_event_memory_artifacts() Send the three artifacts through the SDK API

Local learning and plasticity

import torch
from evospikenet.sdk import SparseEventMemoryConfig, build_sparse_event_memory_model

config = SparseEventMemoryConfig(
    vocab_size=32768,
    d_model=2048,
    num_transformer_blocks=12,
    factor_rank=128,
    connectivity=0.005,
    num_experts=2,
    router_top_k=1,
    adapter_rank=16,
)
model = build_sparse_event_memory_model(config, device="cuda")
optimizer = torch.optim.Adam(model.parameters(), lr=1e-4)

# input_tokens / target_tokens: integer token IDs with shape (batch, sequence)
optimizer.zero_grad(set_to_none=True)
loss = model.sampled_cross_entropy(input_tokens, target_tokens, negative_samples=1024)
loss.backward()
optimizer.step()
local_updates = model.apply_local_plasticity()

Call apply_local_plasticity() after every successful Adam update. It updates the primary INT8 CSR values with a local Hebbian rule and releases recorded activity statistics. If a training step is abandoned, call clear_local_plasticity() instead.

SDK demo application

EvoSpikeNet-Core/examples/sdk/programs/sparse_event_memory_sdk_demo.py tokenizes a short Japanese sentence, performs sampled-softmax learning and local plasticity, and prints a memory report.

cd EvoSpikeNet-Core
python examples/sdk/programs/sparse_event_memory_sdk_demo.py \
  --text "We validate local plasticity in a spiking language model." \
  --steps 3
Option Default Meaning
--tokenizer-name cl-tohoku/bert-base-japanese-v3 Tokenizer name or local path
--device cuda when available Execution device
--d-model 64 Demo state dimension
--num-blocks 2 Sparse event-memory block count
--connectivity 0.05 Connection density per CSR row
--negative-samples 128 Sampled-softmax negative count
--steps 3 Local training steps
--upload false Send artifacts to the SDK API

Uploading artifacts through the API

With --upload, the demo creates a log session using EvoSpikeNetAPIClient and uploads the following with llm_type="SparseEventMemoryLM".

Type File Content
model sparse_event_memory_lm.pth State dict, including INT8 CSR buffers
config config.json Restart configuration with architecture: sparse_event_memory
log memory_report.json Trainable parameter count and persistent CSR storage 
python examples/sdk/programs/sparse_event_memory_sdk_demo.py \
  --upload \
  --base-url http://localhost:8000 \
  --api-key "$EVOSPIKENET_API_KEY"

Tokenizer ownership remains with the application. If tokenizer artifacts must be stored, send an archive separately through upload_artifact() with the same llm_type.

Resuming safely

Confirm that config.json contains architecture: sparse_event_memory, rebuild the same structure with SparseEventMemoryConfig and build_sparse_event_memory_model(), then call load_state_dict(). Dense SpikingEvoTextLM checkpoints are not compatible.

Limitations

  • memory_report() reports persistent storage and is not a peak-VRAM guarantee; activations, optimizer state, and sparse-kernel workspace remain additional costs.
  • PyTorch CSR operations are beta, and GPU performance and supported operations depend on the installed PyTorch/CUDA combination.
  • forward() produces full-vocabulary logits. Use sampled_cross_entropy() to keep training vocabulary memory bounded.
  • This SDK helper is for integer text tokens. It cannot directly accept images, waveforms, MFCCs, or a dense-fusion SpikingEvoMultiModalLM checkpoint. Audio, vision, and multimodal support remains unimplemented work in the MEMERIED SpikeNetLM plan.