# Memory Module

> Local Vector DB for semantic recall and persistent memories

# Memory Module

`Mémory_Módule // Sémantic_Récall`

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

The Memory module provides **privacy-first** local vector storage with semantic search, enabling NPCs to remember past events and recall relevant context.

> *T̷h̵e̸ ̷p̵a̷s̸t̷ ̶s̶h̴a̴p̷e̵s̵ ̶t̷h̵e̸ ̶f̷u̵t̵u̴r̵e̷.*

***

## Overview

The Memory module stores observations locally using **IndexedDB** (browser) or in-memory (Node.js). It provides:

* **Semantic Search**: Find memories relevant to a query
* **Importance Scoring**: Weight memories by significance
* **Temporal Decay**: Old memories fade over time
* **API Sync**: Optional cloud backup

***

## Installation

The Memory module is included in the core SDK:

```bash
npm install forbocai
```

***

## Quick Start

```typescript
import { createMemory } from 'forbocai';

// Initialize memory
const memory = createMemory({
  decay: 'temporal',
  maxContextWindow: 10,
  storageKey: 'npc_memory'
});

// Store an observation
await memory.store(
  'Player saved my life in battle',
  'experience',
  0.95  // High importance
);

// Recall relevant memories
const memories = await memory.recall('Can I trust the player?', 5);
```

***

## Configuration Options

| Option             | Type                     | Default             | Description                             |
| ------------------ | ------------------------ | ------------------- | --------------------------------------- |
| `decay`            | `'none'` \| `'temporal'` | `'none'`            | Memory importance decay strategy        |
| `maxContextWindow` | `number`                 | `10`                | Maximum memories returned per recall    |
| `storageKey`       | `string`                 | `'forbocai_memory'` | IndexedDB database name for persistence |
| `apiUrl`           | `string`                 | API URL             | Optional API URL for cloud sync         |
| `agentId`          | `string`                 | -                   | Agent ID for API calls                  |

***

## API Reference

### `createMemory(config)`

Factory function to create a Memory instance.

```typescript
import { createMemory } from 'forbocai';

const memory = createMemory({
  decay: 'temporal',
  maxContextWindow: 10
});
```

***

### `memory.store(text, type?, importance?)`

Store a new memory observation.

**Parameters:**

* `text` (string): The observation text
* `type` (MemoryType): `'observation'` | `'experience'` | `'fact'` | `'reflection'`
* `importance` (number): 0.0 to 1.0 score

**Returns:** `Promise<MemoryItem>`

```typescript
const mem = await memory.store(
  'Found gold in the dungeon',
  'observation',
  0.6
);
console.log(mem.id);  // "mem_1707012345_abc123"
```

***

### `memory.recall(query, limit?)`

Recall memories relevant to a query using semantic similarity.

**Parameters:**

* `query` (string): The search query
* `limit` (number): Maximum memories to return (default: 5)

**Returns:** `Promise<MemoryItem[]>`

```typescript
const memories = await memory.recall('What happened in battle?', 5);
memories.forEach(m => console.log(m.text));
```

***

### `memory.list(limit?, offset?)`

List all memories with pagination.

**Parameters:**

* `limit` (number): Maximum memories to return (default: 50)
* `offset` (number): Starting offset (default: 0)

**Returns:** `Promise<MemoryItem[]>`

***

### `memory.clear()`

Clear all stored memories. This permanently deletes the LanceDB vector database.

**Returns:** `Promise<void>`

```typescript
// Warning: This action cannot be undone!
await memory.clear();
console.log('All memories erased');
```

> **Note**: This operation removes the underlying vector store directory. Use with caution.

***

### `memory.export()`

Export all memories for backup or Soul portability.

**Returns:** `Promise<MemoryItem[]>`

```typescript
const allMemories = await memory.export();
console.log(`Exporting ${allMemories.length} memories`);
```

***

### `memory.import(memories)`

Import memories from backup or Soul.

**Parameters:**

* `memories` (MemoryItem\[]): Array of memories to import

**Returns:** `Promise<void>`

***

## Pure Functions

For functional programming, use these standalone functions:

### `createMemoryItem(text, type?, importance?)`

Create a new memory item without storing it.

```typescript
import { createMemoryItem } from 'forbocai';

const mem = createMemoryItem('Player attacked', 'observation', 0.8);
```

***

### `applyTemporalDecay(memory, currentTime, decayRate?)`

Apply temporal decay to a memory's importance.

```typescript
import { applyTemporalDecay } from 'forbocai';

const decayed = applyTemporalDecay(memory, Date.now(), 0.001);
console.log(decayed.importance);  // Reduced based on age
```

***

### `rankMemoriesByRelevance(memories, query, limit?)`

Rank memories by relevance to a query.

```typescript
import { rankMemoriesByRelevance } from 'forbocai';

const ranked = rankMemoriesByRelevance(memories, 'battle', 5);
```

***

## Memory Types

| Type          | Description               | Typical Importance |
| ------------- | ------------------------- | ------------------ |
| `observation` | What the agent sees/hears | 0.3 - 0.6          |
| `experience`  | Significant events        | 0.7 - 0.95         |
| `fact`        | Learned information       | 0.5 - 0.8          |
| `reflection`  | Agent's conclusions       | 0.6 - 0.9          |

***

## Temporal Decay

When `decay: 'temporal'` is enabled, older memories become less important over time:

```
Decayed Importance = Original Importance × e^(-decay_rate × age_hours)
```

Default decay rate: `0.001` (memories lose \~50% importance after \~700 hours)

***

## Integration with Soul

Export memories when creating a Soul for portability:

```typescript
import { createMemory, createSoulInstance } from 'forbocai';

const memory = createMemory({ storageKey: 'npc_1' });

// ... store many memories ...

// Export for Soul
const soul = createSoulInstance(
  'agent_1',
  'Kira',
  'A suspicious merchant',
  state,
  await memory.export()  // Include memories in Soul
);

await soul.export();  // Pins to IPFS with memories included
```

***

**ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ**

> *M̵e̶m̵o̷r̴i̷e̷s̷ ̸a̴r̵e̴ ̴t̵h̸e̷ ̸a̷n̶c̷h̸o̸r̸s̶ ̷o̸f̵ ̷i̴d̴e̵n̶t̴i̷t̵y̶.*