saclm 0.1.1

SCLM: Stateful Coherent Language Model - Persistent memory for transformers

🧠 SCLM: Stateful Coherent Language Model

SCLM adds persistent latent memory to transformer language models, enabling better coherence across long conversations and multi-turn generation.

📖 Documentation | 🇫🇷 Version Française | 📝 Paper | 💼 Commercial Licensing

---

⚖️ Licensing

SCLM is Proprietary Software under a dual-licensing model.

🆓 Free for:

• ✅ Personal & hobbyist projects
• ✅ Academic research (non-profit)
• ✅ Small businesses (revenue < $100,000 USD/year)

💼 Commercial License Required for:

• ❗ Organizations with revenue > $100,000 USD/year
• ❗ SaaS products (any revenue)
• ❗ Redistribution in proprietary products

📧 Contact: [e-mail]

---

✨ Features

• 🧠 Persistent Memory: State that evolves across conversation turns
• 🎯 Entity Coherence: Maintains context about characters, places, objects
• ✏️ Edit Mode: Make local changes without affecting global memory
• ⚡ Lightweight: Only ~2-5% additional parameters (EARCP architecture)
• 🔌 Easy Integration: Works with any HuggingFace transformer

📦 Installation

# Basic installation
pip install saclm

# With quantization support
pip install saclm[quantization]

# Full installation (all features)
pip install saclm[full]

🚀 Quick Start

from sclm import SCLMModel

# Load SCLM model from Hugging Face
model = SCLMModel.from_pretrained(
    "amewebstudio/ananke-sclm",     # Pre-trained SCLM model
    load_in_4bit=True  # Optional: 4-bit quantization
)

# Start new conversation
model.reset_state()

# Build context
model.add_context("The wizard Elara lives in Silverwood forest.")
model.add_context("Her familiar is a silver cat named Nimbus.")

# Generate with memory - entities are remembered!
output = model.generate("One day, Elara decided to", max_new_tokens=50)
print(output)
# "One day, Elara decided to take Nimbus on a journey through Silverwood..."

📊 Architecture: EARCP

SCLM uses the EARCP architecture (patent pending):

EARCP = Encapsulation + Alignment + Revision + Coherence + Propagation

Component	Function
Encapsulation	GRU-style state update from hidden states
Alignment	Cross-attention between state and hidden layers
Revision	Drift detection and correction
Coherence	Mixture-of-Experts for consistency
Propagation	State injection into transformer layers

┌─────────────────┐
│  Hidden States  │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│Encaps.│ │Inject │
└───┬───┘ └───────┘
    │
    ▼
┌───────────┐
│  Latent   │
│   State   │───────► Persists across turns
└───────────┘

💡 Use Cases

Interactive Fiction

model.reset_state()

# Build story world
model.add_context("The kingdom of Eldoria was ruled by Queen Lyra.")
model.add_context("The royal advisor Marcus had served for decades.")

# Characters persist in memory
output = model.generate("Marcus approached the throne and said")
# Marcus and Queen Lyra are remembered correctly

Long Conversations

# Memory persists without growing context window
for turn in conversation_turns:
    model.add_context(turn)

# Generate response with all context in memory
response = model.generate("Based on our discussion,")

Creative Writing

# Chapter 1
model.add_context("Chapter 1: Sarah discovered an old map in the attic.")

# Chapter 2 - Sarah is remembered
output = model.generate("Chapter 2: The next morning, Sarah")

⚙️ Configuration

from sclm import SCLMConfig

# Custom configuration
config = SCLMConfig(
    latent_state_dim=256,        # State vector dimension
    n_experts=2,                  # Number of MoE experts
    state_injection_layers=[8, 16],  # Which layers to inject
    alpha_inject=0.02,            # Injection strength
)

# Use with model
model = SCLMModel.from_pretrained("model-name", config=config)

Presets

from sclm.config import get_preset

# Use optimized presets
config = get_preset("mistral-7b")  # or "llama-7b", "phi-2", "tiny"

📖 API Reference

SCLMModel

Method	Description
from_pretrained(name)	Load model from HuggingFace
reset_state()	Reset memory for new conversation
add_context(text)	Add context to memory
generate(prompt)	Generate text with memory
freeze_state()	Freeze memory for editing
save_checkpoint(path)	Save model checkpoint

Properties

Property	Description
state_norm	Current state vector norm
state	Current state tensor

🔬 Benchmarks

Model	EARCP Params	Overhead	Entity Retention
Mistral-7B	91.7M	2.4%	85%
LLaMA-7B	91.7M	2.4%	83%
Phi-2	52.3M	1.9%	81%

🛠️ Advanced Usage

Edit Mode

# Establish context
model.add_context("The sword was blue and ancient.")

# Make edit without changing memory
model.freeze_state()
output = model.generate("The sword was RED")  # State unchanged
model.unfreeze_state()

Memory Tracking

from sclm.utils import MemoryTracker

tracker = MemoryTracker(model)
tracker.add("Context 1")
tracker.add("Context 2")
output = tracker.generate("Prompt")

print(tracker.summary())
tracker.plot_state_evolution()  # Visualize state changes

---

🇫🇷 Documentation Française

Qu'est-ce que SCLM ?

SCLM (Stateful Coherent Language Model) ajoute une mémoire latente persistante aux modèles de langage transformers, permettant une meilleure cohérence dans les longues conversations.

⚖️ Licence

SCLM est un logiciel propriétaire sous un modèle de double licence.

🆓 Gratuit pour :

• ✅ Projets personnels et hobbyistes
• ✅ Recherche académique (non lucratif)
• ✅ Petites entreprises (revenus < 100 000 $ USD/an)

💼 Licence commerciale requise pour :

• ❗ Organisations avec revenus > 100 000 $ USD/an
• ❗ Produits SaaS (tout revenu)
• ❗ Redistribution dans des produits propriétaires

📧 Contact : [e-mail]

Installation

pip install saclm

Démarrage Rapide

from sclm import SCLMModel

# Charger le modèle SCLM depuis Hugging Face
model = SCLMModel.from_pretrained(
    "amewebstudio/ananke-sclm",
    load_in_4bit=True
)

# Nouvelle conversation
model.reset_state()

# Construire le contexte
model.add_context("Le sorcier Élara vit dans la forêt de Boisargent.")
model.add_context("Son familier est un chat argenté nommé Nimbus.")

# Générer avec mémoire
output = model.generate("Un jour, Élara décida de", max_new_tokens=50)
print(output)

Architecture EARCP

Composant	Fonction
Encapsulation	Mise à jour de l'état style GRU
Alignement	Cross-attention état ↔ hidden
Révision	Détection et correction de dérive
Cohérence	Mixture d'Experts (MoE)
Propagation	Injection dans les couches

---

📝 Citation

@article{amega2025sclm,
  title={SCLM: Stateful Coherent Language Models with EARCP Architecture},
  author={Amega, Mike},
  year={2025},
  note={Ame Web Studio - Proprietary}
}

📄 License

Business Source License 1.1 (BSL-1.1) - See LICENSE for details.

Copyright (c) 2025 Mike Amega (Ame Web Studio). All Rights Reserved.

👤 Author

Mike Amega - Ame Web Studio
📧 [e-mail]
🔗 github.com/Volgat

---

💼 Commercial Licensing

For commercial licensing inquiries, enterprise support, or custom development:

📧 Email: [e-mail]

Commercial Benefits:

• ✅ Legal compliance for enterprise use
• ✅ Priority technical support
• ✅ Right to redistribute
• ✅ Warranty and indemnification
• ✅ Custom feature development