Ultra-lightweight framework for on-chain Waifu AI agents
Donation : Fa3myMHdJDUapu99mHnikb3VGU9wU1xoY4dc5smMFufo
Mei is an ultra-lightweight framework for building, deploying, and interacting with on-chain Waifu AI agents on Solana. It combines a personality engine with real-time animation powered by Animation Inc.'s generative animation model, enabling AI characters that are truly alive -- interactive, expressive, and on-chain.
Built in partnership with @Animation-Inc.
graph TB
subgraph Client["Client Layer"]
SDK["TypeScript SDK"]
PY["Python SDK"]
CLI["CLI Tool"]
end
subgraph Core["Core Engine"]
PE["Personality Engine"]
MM["Memory Manager"]
MD["Mood Dynamics"]
TS["Trait System"]
end
subgraph Bridge["Animation Bridge"]
AC["Animation Connector"]
SP["Stream Protocol"]
FC["Frame Codec"]
SM["Session Manager"]
end
subgraph Chain["Solana"]
PROG["Mei Program"]
REG["Agent Registry"]
AGT["Agent Accounts"]
INT["Interaction Records"]
end
subgraph AnimInc["Animation Inc."]
RT["Real-time Animation"]
GM["Generative Model"]
end
SDK --> PE
SDK --> PROG
PY --> PE
PY --> PROG
CLI --> SDK
PE --> MM
PE --> MD
PE --> TS
SDK --> AC
AC --> SP
SP --> FC
AC --> SM
AC --> RT
RT --> GM
PROG --> REG
PROG --> AGT
PROG --> INT
- On-chain agent registry -- agents live as Solana accounts with full ownership, transfer, and lock semantics
- Personality engine -- trait-based system with mood dynamics, emotional decay, and memory recall
- Real-time animation bridge -- direct integration with Animation Inc.'s generative animation model for live character rendering
- Multi-language SDKs -- TypeScript and Python clients with identical capabilities
- Developer CLI -- scaffold, deploy, interact, and monitor agents from the terminal
- Binary frame protocol -- efficient wire format for animation frame streaming
git clone https://github.com/meiworks/mei-framework.git
cd mei-frameworkimport { Connection, Keypair } from "@solana/web3.js";
import { MeiAgent, InteractionKind, hashPayload } from "@meiworks/sdk";
const connection = new Connection("https://api.devnet.solana.com");
const payer = Keypair.generate();
const agent = new MeiAgent(connection, payer);
// Create an on-chain Waifu agent
const state = await agent.create({
name: "Kira",
bio: "A cheerful companion who loves conversations.",
personalityTraits: [
{ name: "warmth", value: 85 },
{ name: "sociability", value: 90 },
{ name: "creativity", value: 70 },
],
animationConfigUri: "https://mei.works/models/kira",
});
// Record an interaction
await agent.interact({
agentAddress: state.address,
interactionType: InteractionKind.Chat,
payloadHash: hashPayload("Hello Kira!"),
});
// Access personality engine
const engine = agent.getPersonalityEngine();
engine.applyInteraction("user", "Hello Kira!", 0.6);
console.log("Mood:", engine.getDominantEmotion());import asyncio
from meiworks import MeiClient
from meiworks.types import CreateAgentParams, TraitDefinition, InteractionKind
async def main():
client = MeiClient()
await client.initialize()
state = await client.agents.create(CreateAgentParams(
name="Sakura",
bio="A creative spirit who brings art to life.",
personality_traits=[
TraitDefinition(name="warmth", value=80),
TraitDefinition(name="creativity", value=85),
],
))
await client.agents.interact(
state.address, InteractionKind.CHAT, "Hello Sakura!"
)
personality = client.agents.get_personality(state.address)
print(f"Emotion: {personality.get_dominant_emotion()}")
asyncio.run(main())# Scaffold a new agent project
mei init my-waifu
# Deploy to Solana devnet
mei deploy --network devnet
# Interactive chat session
mei interact <agent-address> --type chat
# Check agent status
mei status <agent-address>The Mei program is a Solana BPF program written in Rust that manages the agent registry, agent accounts, and interaction records.
| Instruction | Description |
|---|---|
InitializeRegistry |
Create the global agent registry with fee and cooldown config |
CreateAgent |
Register a new Waifu agent with personality traits and animation config |
UpdateAgent |
Modify agent bio, traits, or animation configuration |
RecordInteraction |
Record an on-chain interaction with fee collection |
TransferOwnership |
Transfer agent to a new owner |
SetAgentLock |
Lock or unlock an agent |
UpdateRegistryConfig |
Modify registry fee and cooldown parameters |
erDiagram
Registry ||--o{ Agent : contains
Agent ||--o{ Interaction : receives
Registry {
pubkey authority
u32 agent_count
u32 max_agents
u64 interaction_fee
i64 cooldown_seconds
u64 total_interactions
}
Agent {
pubkey owner
string name
string bio
vec traits
string animation_uri
u64 interaction_count
bool is_locked
}
Interaction {
pubkey agent
pubkey interactor
enum interaction_type
bytes32 payload_hash
u64 fee_paid
i64 timestamp
}
The personality engine drives agent behavior through a three-layer architecture:
Trait System -- Static personality dimensions (warmth, sociability, creativity, etc.) scored 0-100 that influence all behavioral outputs.
Mood Dynamics -- Real-time emotional state modeled in a valence-arousal-dominance space with natural decay toward trait-based baselines. Mood shifts in response to interactions and decays over time.
Memory Manager -- Stores interaction memories with importance scoring, fuzzy search, and automatic consolidation. High-importance memories persist longer and influence mood responses.
// Mood response chain
interaction -> trait modifiers -> mood shift -> emotion detection -> response modifiers
|
v
memory storage
|
v
future recall & contextThe animation bridge provides real-time character animation through Animation Inc.'s generative animation engine:
- Expression smoothing -- blend weight interpolation for natural transitions between emotional states
- Binary frame protocol -- compact wire format with magic bytes, versioning, and efficient blend weight encoding
- Session management -- automatic timeout cleanup, frame rate tracking, and multi-session support
- Gesture system -- parameterized gesture playback with duration control
- Voice synthesis -- optional text-to-speech integration with pitch and speed controls
mei-framework/
program/ Solana BPF program (Rust)
src/
lib.rs Program entry and ID declaration
entrypoint.rs Solana entrypoint
processor.rs Instruction processing logic
instruction.rs Instruction definitions
error.rs Custom error types
state/ Account state definitions
utils/ PDA derivation and validation
sdk/ TypeScript SDK
src/
agent/ Agent lifecycle, registry, types
personality/ Trait system, mood dynamics, memory
chain/ Solana client, instructions, accounts
config/ Configuration schema and loader
utils/ Logger, crypto, encoding, validation
bridge/ Animation Bridge
src/
connector.ts WebSocket connection management
protocol.ts Binary wire protocol
stream.ts Frame rate control and smoothing
codec.ts Animation frame serialization
session.ts Session lifecycle management
cli/ Developer CLI
src/
commands/ init, deploy, interact, config, status
utils/ Display, prompts, config management
python/ Python SDK
meiworks/
client.py High-level client
agent.py Agent management
personality.py Personality configuration
animation.py Animation bridge
chain.py Solana interaction
examples/ Usage examples
basic-agent/ TypeScript basic agent
custom-personality/ TypeScript personality customization
python-agent/ Python full lifecycle example
MIT
