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:

$
npm install forbocai

Quick Start

1
import { createMemory } from 'forbocai';
2
3
// Initialize memory
4
const memory = createMemory({
5
  decay: 'temporal',
6
  maxContextWindow: 10,
7
  storageKey: 'npc_memory'
8
});
9
10
// Store an observation
11
await memory.store(
12
  'Player saved my life in battle',
13
  'experience',
14
  0.95  // High importance
15
);
16
17
// Recall relevant memories
18
const memories = await memory.recall('Can I trust the player?', 5);

Configuration Options

API Reference

createMemory(config)

Factory function to create a Memory instance.

1
import { createMemory } from 'forbocai';
2
3
const memory = createMemory({
4
  decay: 'temporal',
5
  maxContextWindow: 10
6
});

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>

1
const mem = await memory.store(
2
  'Found gold in the dungeon',
3
  'observation',
4
  0.6
5
);
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[]>

1
const memories = await memory.recall('What happened in battle?', 5);
2
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>

1
// Warning: This action cannot be undone!
2
await memory.clear();
3
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[]>

1
const allMemories = await memory.export();
2
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.

1
import { createMemoryItem } from 'forbocai';
2
3
const mem = createMemoryItem('Player attacked', 'observation', 0.8);

applyTemporalDecay(memory, currentTime, decayRate?)

Apply temporal decay to a memory’s importance.

1
import { applyTemporalDecay } from 'forbocai';
2
3
const decayed = applyTemporalDecay(memory, Date.now(), 0.001);
4
console.log(decayed.importance);  // Reduced based on age

rankMemoriesByRelevance(memories, query, limit?)

Rank memories by relevance to a query.

1
import { rankMemoriesByRelevance } from 'forbocai';
2
3
const ranked = rankMemoriesByRelevance(memories, 'battle', 5);

Memory Types

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:

1
import { createMemory, createSoulInstance } from 'forbocai';
2
3
const memory = createMemory({ storageKey: 'npc_1' });
4
5
// ... store many memories ...
6
7
// Export for Soul
8
const soul = createSoulInstance(
9
  'agent_1',
10
  'Kira',
11
  'A suspicious merchant',
12
  state,
13
  await memory.export()  // Include memories in Soul
14
);
15
16
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̶.