Features

• File system-based storage for SamoAI entities
• Persistent memory and state management
• Support for agents, users, locations, items, and gimmicks
• TypeScript support with full type safety

Installation

Install the package using npm:

npm install @little-samo/samo-ai-repository-storage

Or using yarn:

yarn add @little-samo/samo-ai-repository-storage

Usage

Basic Setup

import {
  AgentStorage,
  UserStorage,
  LocationStorage,
  ItemStorage,
  GimmickStorage
} from '@little-samo/samo-ai-repository-storage';
import { WorldManager } from '@little-samo/samo-ai';

// Initialize storage instances
const agentStorage = new AgentStorage(
  './models/agents',    // Path to agent model files
  './states/agents'     // Path to agent state files
);

const userStorage = new UserStorage(
  './models/users',
  './states/users'
);

const locationStorage = new LocationStorage(
  './models/locations',
  './states/locations'
);

const itemStorage = new ItemStorage(
  './states/items'      // Only state path needed for items
);

const gimmickStorage = new GimmickStorage(
  './states/gimmicks'   // Only state path needed for gimmicks
);

// Initialize with existing data
await agentStorage.initialize(['samo', 'nyx']); // Load samo.json and nyx.json
await userStorage.initialize(['lucid']); // Load lucid.json
await locationStorage.initialize(['empty']);
await itemStorage.initialize(['agent:1', 'user:1']); // Initialize inventories
await gimmickStorage.initialize([1]); // Initialize gimmicks for location

// Initialize WorldManager with all repositories
WorldManager.initialize({
  agentRepository: agentStorage,
  gimmickRepository: gimmickStorage,
  itemRepository: itemStorage,
  locationRepository: locationStorage,
  userRepository: userStorage,
});

Environment Configuration

To use LLM features, you need to configure API keys for the supported platforms. Set the following environment variables:

• OpenAI: OPENAI_API_KEY=your_openai_api_key
• Gemini: GEMINI_API_KEY=your_gemini_api_key
• Anthropic: ANTHROPIC_API_KEY=your_anthropic_api_key

You can set these in several ways:

• Set environment variables directly: OPENAI_API_KEY=sk-... node your-app.js
• Use dotenv package with a .env file:

  OPENAI_API_KEY=sk-...
  GEMINI_API_KEY=AI...
  ANTHROPIC_API_KEY=sk-ant-...

• Set them in your system environment

Note: Currently, API keys are shared across all users. In a production environment, you would typically store user-specific API keys.

File Structure

The storage system expects the following directory structure:

your-project/
├── models/
│   ├── agents/
│   │   ├── samo.json
│   │   └── nyx.json
│   ├── users/
│   │   └── lucid.json
│   └── locations/
│       └── empty.json
└── states/
    ├── agents/
    │   ├── samo.json
    │   └── nyx.json
    ├── users/
    │   └── lucid.json
    ├── locations/
    │   └── empty.json
    ├── items/
    │   ├── items_agent_1.json
    │   └── items_user_1.json
    └── gimmicks/
        └── gimmicks_1.json

• models/: Static entity definitions (agents, users, locations only) - Must be created manually
• states/: Dynamic runtime data that changes during execution - Created automatically if missing
• items/: Inventory data per entity (format: items_{entityType}_{entityId}.json)
• gimmicks/: Gimmick states per location (format: gimmicks_{locationId}.json)

Note: Items and gimmicks don't have model files - they are created and managed entirely through the state files. The states/ directories will be automatically created during initialization if they don't exist.

Learn More

• SamoAI Core Library - The main SamoAI framework
• SamoAI Example CLI - Example implementation using this storage library

License

MIT License