Skip to main content

​
Store Memory

Store data persistently in the 0G decentralized storage network for AI agents and applications.

​
Method

memory.store(entry: MemoryEntry): Promise<MemoryResult>

​
Parameters

​
entry
MemoryEntry
required
The memory entry to store
​
entry.key
string
required
Unique identifier for the memory entry
​
entry.value
any
required
The data to store (will be JSON serialized)
​
entry.metadata
Record<string, any>
Additional metadata for the entry
​
entry.tags
string[]
Tags for categorizing and searching the entry
​
entry.ttl
number
Time-to-live in seconds (optional expiration)

​
Response

​
success
boolean
Whether the storage operation succeeded
​
key
string
The key of the stored entry
​
hash
string
The content hash on the 0G network
​
timestamp
Date
When the entry was stored
​
size
number
Size of the stored data in bytes

​
Examples

import { Memory } from 'nebula-sdk';

const memory = new Memory({
  storageKey: 'user-session-123',
  apiKey: 'your-api-key'
});

// Store simple data
const result = await memory.store({
  key: 'user_preferences',
  value: {
    theme: 'dark',
    language: 'en',
    notifications: true
  }
});

console.log('Stored successfully:', result.success);
console.log('Content hash:', result.hash);

​
Advanced Usage

​
Conditional Storage

// Only store if key doesn't exist
try {
  const existing = await memory.retrieve('user_profile');
  if (!existing) {
    await memory.store({
      key: 'user_profile',
      value: { name: 'John', age: 30 }
    });
  }
} catch (error) {
  // Key doesn't exist, safe to store
  await memory.store({
    key: 'user_profile',
    value: { name: 'John', age: 30 }
  });
}

​
Versioned Storage

// Store with version control
const version = Date.now();
const result = await memory.store({
  key: `document_v${version}`,
  value: {
    content: 'Updated document content',
    version: version,
    previousVersion: 'document_v1234567890'
  },
  metadata: {
    author: 'user123',
    changeType: 'content_update'
  },
  tags: ['document', 'versioned']
});

// Also update the "latest" pointer
await memory.store({
  key: 'document_latest',
  value: { currentVersion: `document_v${version}` }
});

​
Large Data Storage

// Store large objects efficiently
const largeDataset = {
  // ... large data object
};

// Compress before storing (optional)
const compressed = JSON.stringify(largeDataset);

const result = await memory.store({
  key: 'large_dataset_001',
  value: largeDataset,
  metadata: {
    originalSize: JSON.stringify(largeDataset).length,
    compressed: false,
    dataType: 'training_data'
  },
  tags: ['dataset', 'large', 'training']
});

if (result.size > 1024 * 1024) { // 1MB
  console.warn('Large storage detected:', result.size, 'bytes');
}

​
Error Handling

try {
  const result = await memory.store({
    key: 'test_data',
    value: { message: 'Hello World' }
  });
  
  if (!result.success) {
    console.error('Storage failed');
  }
} catch (error) {
  switch (error.code) {
    case 'STORAGE_QUOTA_EXCEEDED':
      console.error('Storage quota exceeded');
      break;
    case 'INVALID_KEY':
      console.error('Invalid key format');
      break;
    case 'NETWORK_ERROR':
      console.error('Network connection failed');
      break;
    case 'SERIALIZATION_ERROR':
      console.error('Data cannot be serialized');
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

​
Storage Patterns

​
Cache Pattern

class MemoryCache {
  constructor(private memory: Memory) {}
  
  async set(key: string, value: any, ttl: number = 3600) {
    return await this.memory.store({
      key: `cache:${key}`,
      value,
      ttl,
      tags: ['cache']
    });
  }
  
  async get(key: string) {
    try {
      const result = await this.memory.retrieve(`cache:${key}`);
      return result?.value;
    } catch {
      return null;
    }
  }
}

const cache = new MemoryCache(memory);
await cache.set('api_response', { data: 'cached' }, 1800);

​
Event Sourcing

// Store events for replay
async function storeEvent(eventType: string, eventData: any) {
  const eventId = `event_${Date.now()}_${Math.random()}`;
  
  return await memory.store({
    key: eventId,
    value: {
      type: eventType,
      data: eventData,
      timestamp: new Date()
    },
    metadata: {
      eventType,
      aggregateId: eventData.aggregateId
    },
    tags: ['event', eventType]
  });
}

await storeEvent('user_registered', {
  aggregateId: 'user123',
  email: 'user@example.com'
});

​
Best Practices

​
Key Naming

// Use consistent key naming patterns
const keyPatterns = {
  user: (id: string) => `user:${id}`,
  session: (id: string) => `session:${id}`,
  cache: (key: string) => `cache:${key}`,
  config: (name: string) => `config:${name}`,
  temp: (id: string) => `temp:${id}`
};

await memory.store({
  key: keyPatterns.user('123'),
  value: { name: 'John' }
});

​
Data Validation

function validateMemoryEntry(entry: MemoryEntry): boolean {
  if (!entry.key || typeof entry.key !== 'string') {
    throw new Error('Invalid key');
  }
  
  if (entry.key.length > 255) {
    throw new Error('Key too long');
  }
  
  if (entry.value === undefined) {
    throw new Error('Value is required');
  }
  
  return true;
}

// Use before storing
validateMemoryEntry(entry);
await memory.store(entry);

​
Performance Tips

  1. Batch operations when storing multiple entries
  2. Use appropriate TTL to prevent storage bloat
  3. Compress large data before storing
  4. Use tags efficiently for better search performance
  5. Monitor storage usage to avoid quota issues