> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.forboc.ai/npm/soul/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.forboc.ai/_mcp/server.

# Soul Module

The current SDK exposes Soul workflows through thunks and CLI commands.

## Export Soul

```typescript
import { createSDKStore, setNPCInfo, remoteExportSoulThunk } from '@forbocai/core';

const store = createSDKStore();

store.dispatch(setNPCInfo({ id: 'npc_1', persona: 'A careful merchant' }));

const exported = await store.dispatch(remoteExportSoulThunk({
  npcId: 'npc_1',
  apiUrl: 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY
})).unwrap();

console.log(exported.txId, exported.url);
```

## Import Soul by Transaction ID

```typescript
import { importSoulFromArweaveThunk } from '@forbocai/core';

const soul = await store.dispatch(importSoulFromArweaveThunk({
  txId: 'arweave_tx_id_here',
  apiUrl: 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY
})).unwrap();

console.log(soul.name, soul.persona);
```

## List Souls

```typescript
import { getSoulListThunk } from '@forbocai/core';

const souls = await store.dispatch(getSoulListThunk({
  limit: 20,
  apiUrl: 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY
})).unwrap();

console.log(souls.length);
```

## CLI

```bash
npx forbocai soul export <npcId>
npx forbocai soul import <txId-or-local-json-file>
npx forbocai soul list 20
npx forbocai soul chat <npcId>
```

> Export, import, and list portable NPC souls via API-backed thunks