SimpleMem Integration

SimpleMem is a Python CLI bridge that provides the persistence layer for Nity's memory operations. It wraps semantic memory functionality behind a command-line interface that the TypeScript extensions invoke via subprocess.

Interface

# Store an episode
simplemem store --namespace episodes --key <id> --value <json>
 
# Retrieve episodes
simplemem query --namespace episodes --filter '{"taskType":"code"}' --limit 10
 
# Store brain state
simplemem store --namespace brain --key session_<id> --value <content>
 
# Search by similarity
simplemem search --namespace episodes --query "authentication implementation" --top 5

Architecture

TypeScript Extension (nity-memory)
  └── SimpleMem Bridge (simplemem-bridge.ts)
       └── spawn('python', ['-m', 'simplemem', ...])
            └── SimpleMem CLI (Python)
                 └── Storage Backend (filesystem / vector store)

Graceful Degradation

⚠️

SimpleMem handles missing Voyager installations gracefully. If the Python environment or simplemem module is not found, the bridge falls back to in-memory storage for the current session. Data is not persisted across sessions in fallback mode.

The bridge detects failures at three levels:

Level	Detection	Fallback
Python not found	`spawn` error	In-memory HashMap
SimpleMem module missing	`ModuleNotFoundError`	In-memory HashMap
Storage backend unavailable	Exit code 1	In-memory HashMap with warning

Bridge Interface

interface SimpleMemBridge {
  store(namespace: string, key: string, value: string): Promise<void>
  query(namespace: string, filter: Record<string, unknown>): Promise<string[]>
  search(namespace: string, query: string, top: number): Promise<SearchResult[]>
  isAvailable(): boolean
  getStatus(): BridgeStatus
}
 
interface BridgeStatus {
  available: boolean
  pythonPath: string | null
  simplememVersion: string | null
  storageBackend: 'filesystem' | 'vector' | 'memory-fallback'
  lastError: string | null
}
 
interface SearchResult {
  key: string
  score: number
  content: string
}

Usage in Nity Memory

SimpleMem is called by:

BrainManager — persist() stores brain state under brain namespace
EpisodeRecorder — record() stores episodes under episodes namespace
MemoryRecall — search() performs similarity-based episode retrieval
RalphUniversal — query() retrieves historical effectiveness data

// Example: storing an episode
const bridge = new SimpleMemBridge()
 
await bridge.store('episodes', episode.id, JSON.stringify({
  task: episode.task,
  taskType: episode.taskType,
  approach: episode.approach,
  adapter: episode.adapter,
  outcome: episode.outcome,
  tokensUsed: episode.tokensUsed,
  duration: episode.duration,
  timestamp: episode.timestamp.toISOString(),
  reflections: episode.reflections
}))

Session Brain Episode Recording

Ralph Universal Nity Memory