Seim0 - Decentralized Memory Layer on Sei Blockchain

Seim0 is a revolutionary memory layer that stores AI memories directly on the Sei blockchain, ensuring decentralized, immutable, and globally accessible memory storage. Built on top of Sei's high-performance EVM-compatible blockchain, Seim0 combines the power of decentralized storage with IPFS for content and smart contracts for indexing.

🌟 Features

• 🔗 Blockchain-Native: Memories stored directly on Sei blockchain with immutable transaction hashes
• 📡 IPFS Integration: Content stored on IPFS for decentralized, censorship-resistant access
• ⚡ High Performance: Built on Sei's optimized blockchain for fast transaction processing
• 🔍 Smart Contract Indexing: Efficient memory discovery through on-chain smart contracts
• 💰 Cost Effective: Leverages Sei's low transaction costs for affordable memory operations
• 🛡️ Decentralized: No central authority - your memories are truly yours
• 🔐 Cryptographic Security: All operations secured by blockchain cryptography

📦 Installation

npm install seim0

🚀 Quick Start

1. Setup Environment

Create a .env file in your project root:

PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_KEY=your_pinata_secret_key

# Required for on-chain transactions
PRIVATE_KEY=your_wallet_private_key
GOOGLE_API_KEY="your_gemini_or_openai_api_key"

2. Basic Usage

import { MemoryClient } from "seim0";
import { ethers } from "ethers";

const provider = new ethers.providers.JsonRpcProvider(
  "https://evm-rpc-testnet.sei-apis.com",
);

const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

const memory = new MemoryClient({
  network: "testnet",
  signer: signer,
  llm: {
    provider: "google",
    config: {
      apiKey: process.env.GOOGLE_API_KEY,
      model: "gemini-2.0-flash",
    },
  },
  embedder: {
    provider: "google",
    config: {
      apiKey: process.env.GOOGLE_API_KEY,
      model: "text-embedding-004",
    },
  },
});

3. Adding Memories

// Add a memory to the blockchain
const conversation = [
  {
    role: "user" as const,
    content:
      "Hi, I'm David and I work as a blockchain developer at Ethereum Foundation. I specialize in smart contract security and love DeFi protocols.",
  },
  {
    role: "assistant" as const,
    content:
      "Nice to meet you David! Smart contract security is crucial in DeFi. What are your favorite protocols to work with?",
  },
  {
    role: "user" as const,
    content:
      "I really enjoy working with Uniswap and Compound. I also contribute to OpenZeppelin's security audits on weekends.",
  },
];

const addResult = await memory.add(conversation, {
  user_id: "david_blockchain_dev",
  agent_id: "sei-assistant",
  run_id: "onboarding-001",
  metadata: { topic: "intro", project: "sei_memory_test" },
});

console.log("Memory stored on blockchain!");
console.log("Transaction Hash:", addResult.txHash);
console.log("IPFS CID:", addResult.cid);

4. Searching Memories

// Search memories on the blockchain
const searchResults = await memory.search("What do you know about me?", {
  user_id: "david_blockchain_dev",
  agent_id: "sei-assistant", // optional
  run_id: "onboarding-001", // optional
  limit: 3,
});

console.log(`Found ${searchResults.length} memories:`);
searchResults.forEach((memory, index) => {
  console.log(`${index + 1}. ${memory.memory}`);
});

5. Getting All Memories

// Get all memories for a user
const allUserMemories = await memory.getAll({
  user_id: "david_blockchain_dev",
});
// Get all memories for a user for a specific agent
const agentMemories = await memory.getAll({
  user_id: "david_blockchain_dev",
  agent_id: "sei-assistant",
});
// Get all memories for a specific conversation/run
const runMemories = await memory.getAll({
  user_id: "david_blockchain_dev",
  run_id: "onboarding-001",
});
// Narrow to a specific agent + run
const scopedMemories = await memory.getAll({
  user_id: "david_blockchain_dev",
  agent_id: "sei-assistant",
  run_id: "onboarding-001",
});

console.log(
  `Totals: user=${allUserMemories.length}, agent=${agentMemories.length}, run=${runMemories.length}, scoped=${scopedMemories.length}`,
);

🧭 Scoped Organization (user_id, agent_id, run_id)

All writes go on-chain/IPFS. Use the trio of identifiers to control organization and retrieval.

// Store with full context
await memory.add("User prefers vegetarian food", {
  user_id: "alice",
  agent_id: "diet-assistant",
  run_id: "consultation-001",
});

// Retrieve memories with different scopes
const allUser = await memory.getAll({ user_id: "alice" });
const byAgent = await memory.getAll({
  user_id: "alice",
  agent_id: "diet-assistant",
});
const byRun = await memory.getAll({
  user_id: "alice",
  run_id: "consultation-001",
});
const agentRun = await memory.getAll({
  user_id: "alice",
  agent_id: "diet-assistant",
  run_id: "consultation-001",
});

// Search with context
const general = await memory.search("What do you know about me?", {
  user_id: "alice",
});
const agentSearch = await memory.search("What do you know about me?", {
  user_id: "alice",
  agent_id: "diet-assistant",
});
const runSearch = await memory.search("What do you know about me?", {
  user_id: "alice",
  run_id: "consultation-001",
});

🔧 Configuration

That's it! The package automatically handles:

✅ Network Selection: Just specify "testnet" or "mainnet"
✅ Smart Contracts: Pre-deployed contracts are used automatically
✅ IPFS Gateway: Your Pinata credentials are used for storage
✅ Blockchain RPC: Optimal RPC endpoints are selected automatically

No contract addresses, no RPC URLs, no complex setup needed!

🏗️ Architecture

Seim0 uses a multi-layered architecture:

1. Smart Contracts: Pre-deployed contracts handle:

   • Memory indexing and metadata management
   • Access control and permissions
   • Transaction fees and payments

2. IPFS Storage: Your Pinata account stores:

   • Decentralized content storage
   • Immutable content addressing
   • Global accessibility

3. Blockchain Integration: Sei testnet/mainnet provides:

   • Fast transaction processing
   • Immutable transaction history
   • Cryptographic verification

�️ Development

Building the Project

npm run build

Running Examples

npm run sei:example

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

🆘 Getting Help

If you have any questions or need assistance:

• GitHub Issues: Report bugs or request features
• Documentation: Check the examples in src/oss/examples/