1
import { createSoulInstance, importSoulFromIPFS } from 'forbocai';
2
3
// Create a Soul from agent data
4
const soul = createSoulInstance(
5
  'agent_123',
6
  'Kira the Merchant',
7
  'A suspicious merchant who distrusts adventurers',
8
  { mood: 'suspicious', inventory: ['rusty_key'] },
9
  memories
10
);
11
12
// Export to IPFS
13
const { cid, ipfsUrl } = await soul.export();
14
console.log(`Soul pinned: ${ipfsUrl}`);
15
// ipfs://QmXyz...
16
17
// Import in another game
18
const importedSoul = await importSoulFromIPFS(cid);

1
import { createSoulInstance } from 'forbocai';
2
3
const soul = createSoulInstance(
4
  'agent_1',
5
  'Kira the Merchant',
6
  'A suspicious merchant who was once cheated by adventurers.',
7
  {
8
    mood: 'suspicious',
9
    inventory: ['rusty_key', 'healing_potion'],
10
    skills: { haggle: 0.8, detect_lies: 0.6 },
11
    relationships: { player: -0.3 }
12
  },
13
  memories  // Optional: from Memory module
14
);

1
interface SoulExportResult {
2
  cid: string;           // IPFS Content ID
3
  ipfsUrl: string;       // Full IPFS URL
4
  signature?: string;    // Cryptographic signature
5
  soul: Soul;            // The exported Soul data
6
}

1
const result = await soul.export({
2
  includeMemories: true,
3
  sign: true
4
});
5
6
console.log(result.cid);     // "QmXyz..."
7
console.log(result.ipfsUrl); // "ipfs://QmXyz..."

1
const soulData = soul.toJSON();
2
console.log(soulData.persona);

1
import { importSoulFromIPFS } from 'forbocai';
2
3
const soul = await importSoulFromIPFS('QmXyz...');
4
console.log(soul.persona);
5
// "A suspicious merchant who distrusts adventurers"

1
import { createAgentFromSoul } from 'forbocai';
2
3
const { agentId, persona } = await createAgentFromSoul(
4
  'QmXyz...',
5
  cortexId
6
);
7
8
console.log(`Created agent ${agentId} with persona: ${persona}`);

1
import { getSoulList } from 'forbocai';
2
3
const souls = await getSoulList(10);
4
5
souls.forEach(soul => {
6
  console.log(`${soul.name}`);
7
  console.log(`  CID: ${soul.cid}`);
8
  console.log(`  IPFS: ${soul.ipfsUrl}`);
9
  console.log(`  Exported: ${soul.exportedAt}`);
10
});

1
interface SoulListEntry {
2
  cid: string;
3
  name: string;
4
  agentId?: string;
5
  exportedAt: string;
6
  ipfsUrl: string;
7
}

1
import { createSoul } from 'forbocai';
2
3
const soulData = createSoul(
4
  'agent_1',
5
  'Kira',
6
  'A suspicious merchant',
7
  { mood: 'suspicious', inventory: [] },
8
  []
9
);

1
import { serializeSoul } from 'forbocai';
2
3
const json = serializeSoul(soulData);
4
// Store or transmit as string

1
import { deserializeSoul } from 'forbocai';
2
3
const soul = deserializeSoul(jsonString);

1
import { validateSoul } from 'forbocai';
2
3
const { valid, errors } = validateSoul(soulData);
4
if (!valid) {
5
  console.error('Invalid Soul:', errors);
6
}

1
interface Soul {
2
  id: string;              // Unique identifier
3
  version: string;         // Schema version (e.g., "1.0.0")
4
  name: string;            // Display name
5
  persona: string;         // Personality description
6
  state: AgentState;       // Current state
7
  memories: MemoryItem[];  // Accumulated memories
8
  signature?: string;      // Ownership signature
9
}
10
11
interface AgentState {
12
  mood: string;
13
  inventory: string[];
14
  skills: Record<string, number>;
15
  relationships: Record<string, number>;
16
}

1
// Coming soon: Metaplex integration
2
import { mintSoulNFT } from 'forbocai';
3
4
const { cid } = await soul.export();
5
6
// Mint NFT pointing to Soul
7
const nft = await mintSoulNFT({
8
  cid,
9
  name: soul.toJSON().name,
10
  symbol: 'SOUL',
11
  royalties: 5  // 5% royalties
12
});
13
14
console.log(`NFT minted: ${nft.mint}`);

1
// In Game A
2
const memory = createMemory({ storageKey: 'game_a_npc' });
3
// ... NPC accumulates memories ...
4
5
const soul = createSoulInstance(
6
  npc.id,
7
  npc.name,
8
  npc.persona,
9
  npc.getState(),
10
  memory.export()
11
);
12
13
const { cid } = await soul.export();
14
// Give CID to player for use in Game B

1
// In Game B
2
const { agentId, persona } = await createAgentFromSoul(cid, cortexId);
3
4
// Hydrate memories
5
const soul = await importSoulFromIPFS(cid);
6
const memory = createMemory({ storageKey: `game_b_${agentId}` });
7
await memory.import(soul.memories);
8
9
// NPC now has all memories from Game A!