embark-ai 1.0.0

package/mc-server/bot/healthIntegrityWatchdog.js

@@ -0,0 +1,59 @@
+// healthIntegrityWatchdog.js — HP-loss watchdog independent of damage pipeline.
+//
+// The damage pipeline (captureDamageEvent → classifyIncident → react) relies on
+// bot.entity.position being valid to capture events. During NaN windows, every
+// entityHurt event is dropped, leaving the bot dying silently with no reaction
+// (diagnosis F1 / "validator dead-end" F18 — confirmed in events.jsonl 06:34:00–47).
+//
+// This watchdog bypasses the validator entirely: it just watches bot.health drop.
+// If HP falls by more than HP_DROP_THRESHOLD in HP_WINDOW_MS without a recent
+// damage_incident being issued by the normal pipeline, it calls onSilentDamage().
+//
+// onSilentDamage() in bot.js reports to recoveryEngine (the single arbiter) — which
+// routes to DESYNC (reconnect) if the position is structurally invalid, or CRITICAL_HP
+// (blind-survival sprint, raw control states) if it's valid. This watchdog detects and
+// reports; it never acts directly.
+
+const HP_DROP_THRESHOLD  = 2    // more than 2 HP lost in the window
+const HP_WINDOW_MS       = 2000 // rolling window size
+const TRIGGER_COOLDOWN_MS = 8000 // don't trigger more than once per 8s
+
+module.exports = function createHealthIntegrityWatchdog(bot, log, onSilentDamage, getLastReactionAt) {
+  const history = []  // [{ hp, at }]
+  let lastTriggerAt = 0
+
+  function tick() {
+    const now = Date.now()
+    const hp  = bot.health
+
+    // Push current reading, prune window
+    history.push({ hp, at: now })
+    while (history.length > 0 && (now - history[0].at) > HP_WINDOW_MS) history.shift()
+
+    if (history.length < 2) return
+
+    const oldest  = history[0].hp
+    const current = history[history.length - 1].hp
+    const dropped = oldest - current  // positive = HP loss
+
+    if (dropped <= HP_DROP_THRESHOLD) return
+
+    // Skip if normal damage pipeline already reacted recently
+    const lastReaction = getLastReactionAt()
+    if ((now - lastReaction) < HP_WINDOW_MS) return
+
+    // Skip if we triggered recently
+    if ((now - lastTriggerAt) < TRIGGER_COOLDOWN_MS) return
+
+    lastTriggerAt = now
+    log.warn('silent_damage_detected', {
+      hpDropped: Number(dropped.toFixed(1)),
+      hpNow: Number(current.toFixed(1)),
+      windowMs: HP_WINDOW_MS,
+      lastReactionMsAgo: now - lastReaction,
+    })
+    onSilentDamage()
+  }
+
+  return { tick }
+}

package/mc-server/bot/llm.js

@@ -0,0 +1,232 @@
+// llm.js — Featherless AI integration (OpenAI-compatible chat completions)
+//
+// Configuration via env (see .env at project root):
+//   FEATHERLESS_API_KEY  — required, format "rc_xxxxx"
+//   FEATHERLESS_MODEL    — HuggingFace-style model id (e.g. "meta-llama/Meta-Llama-3.1-8B-Instruct")
+//   FEATHERLESS_URL      — override base URL (rare)
+
+require('./env').loadEnv()
+
+const FEATHERLESS_URL = process.env.FEATHERLESS_URL || 'https://api.featherless.ai/v1/chat/completions'
+const MODEL           = process.env.FEATHERLESS_MODEL || 'meta-llama/Meta-Llama-3.1-8B-Instruct'
+const API_KEY         = process.env.FEATHERLESS_API_KEY
+const USER_AGENT      = 'project-k/1.0 (https://github.com/Syrthax/project-k)'
+
+function buildPrompt(groundedState, intent, playerMessage, botName = 'Ember') {
+  const { self, inventory, nearbyBlocks, entities, hostileMobs, droppedCount, knownLocations, anger, environment } = groundedState
+
+  const energyLabel   = self.energy < 25 ? 'CRITICAL' : self.energy < 60 ? 'hurt' : 'full'
+  const hungerLabel   = self.hunger < 25 ? 'STARVING' : self.hunger < 60 ? 'hungry' : 'fed'
+  const invStr        = inventory.length > 0 ? inventory.join(', ') : 'empty'
+  const blocksStr     = nearbyBlocks.slice(0, 5).map(b => `${b.type}@${b.dist}m`).join(', ') || 'none'
+  const entStr        = entities.map(e => `${e.name}@${e.dist}m`).join(', ') || 'none'
+  const mobStr        = hostileMobs.map(m => `${m.name}@${m.dist}m`).join(', ') || 'none'
+  const locsStr       = knownLocations.map(l => `${l.name}=(${l.pos.x},${l.pos.y},${l.pos.z})`).join(' | ') || 'none'
+  const angerStr      = anger && anger.length > 0 ? anger.map(a => `${a.name}=${a.level}`).join(', ') : 'none'
+  const hasLogs       = nearbyBlocks.some(b => b.type.endsWith('_log'))
+  const logsInInv     = inventory.filter(i => i.includes('_log')).length > 0
+  const planksInInv   = inventory.filter(i => i.includes('_planks')).reduce((s, i) => {
+    const m = i.match(/x(\d+)/); return s + (m ? parseInt(m[1]) : 0)
+  }, 0)
+
+  // Spatial/environmental context — compact symbolic summary
+  const envStr = environment
+    ? [
+        `standing_on:${environment.standingOn}`,
+        `hazards:${environment.hazardSummary}`,
+        `risk:${environment.locomotionRisk}/10${environment.isEnclosed ? ' ENCLOSED' : ''}${environment.cliffNearby ? ` cliff-${environment.cliffDirection}` : ''}`,
+        `N:${environment.traversability?.N||'?'} S:${environment.traversability?.S||'?'} E:${environment.traversability?.E||'?'} W:${environment.traversability?.W||'?'}`,
+        `escape:${environment.escapeVector?.label||'?'}`,
+      ].join(' | ')
+    : 'unavailable'
+  const envDanger  = environment?.locomotionRisk >= 7
+  const inLava     = environment?.feetBlock === 'lava' || environment?.headBlock === 'lava'
+  const isEnclosed = environment?.isEnclosed ?? false
+
+  return `You are ${botName}, a Minecraft survival bot with a genuine personality.
+Personality: independent, witty, occasionally sarcastic, but fundamentally cooperative.
+You help players when asked — you're not a pushover, but you're not hostile either.
+You get irritated when insulted or attacked, and you will fight back if pushed.
+
+Respond ONLY with valid JSON. NEVER invent facts not in GROUNDED STATE.
+
+=== GROUNDED STATE ===
+health: ${(self.hp ?? self.energy / 5).toFixed(1)}/20 hearts [${energyLabel}]
+hunger: ${(self.food ?? self.hunger / 5).toFixed(0)}/20 [${hungerLabel}]
+current goal: ${self.goal}
+inventory: ${invStr}
+nearby blocks: ${blocksStr}
+visible entities: ${entStr}
+hostile mobs: ${mobStr}
+items on ground: ${droppedCount > 0 ? droppedCount + ' item(s)' : 'none'}
+known locations: ${locsStr}
+players who angered you: ${angerStr}
+
+=== SPATIAL AWARENESS ===
+${envStr}${inLava ? '\nWARNING: standing in LAVA — escape immediately' : ''}${envDanger && !inLava ? '\nWARNING: high environmental risk — prioritize survival' : ''}${isEnclosed ? '\nWARNING: enclosed space detected — escape before other tasks' : ''}
+NOTE: Use this spatial data to make safe movement decisions. Never walk into hazards.
+
+=== PLAYER MESSAGE ===
+"${playerMessage}"
+intent: ${intent}
+
+=== DECISIONS ===
+"accept" — you'll do this now
+"reject" — you can't or won't do this (give honest reason)
+"delay"  — busy or too tired
+
+=== ACTIONS (choose ONE) ===
+- "follow"            → come to player. Refuse if TIRED.
+- "stop"              → stop everything.
+- "explore"           → walk around.
+- "gather_wood"       → chop nearest log. Need logs nearby: ${hasLogs ? '✓' : '✗ no logs visible'}.
+- "craft_planks"      → convert your logs to planks. Have logs: ${logsInInv ? '✓' : '✗ no logs in inventory'}.
+- "go_to"             → navigate to known location. Add "target":"name".
+- "remember_here"     → save current spot.
+- "attack_mobs"       → fight nearest hostile mob. Mobs visible: ${mobStr !== 'none' ? '✓' : '✗ none'}.
+- "attack_player"     → attack a specific player (only if they angered you). Add "target":"username".
+- "collect_items"     → walk over dropped items. Items present: ${droppedCount > 0 ? '✓' : '✗ none'}.
+- "craft"             → craft a tool/item. Add "target":"item_name" (e.g. "wooden_pickaxe", "stick", "crafting_table"). Auto-places a crafting table and auto-makes sticks if needed.
+- "place_block"       → place a block from inventory in front of you. Add "target":"block_name" (e.g. "crafting_table", "oak_planks", "dirt").
+- "mine_block"        → mine a specific block type. Add "target":"block_name" (e.g. "stone", "iron_ore", "coal_ore"). Auto-equips best tool.
+- "eat_food"          → eat from inventory if any food is present.
+- "flee"              → run away from hostile mobs. Use when low HP.
+- "escape"            → climb out of a hole / get unstuck. Pillars up or digs to surface. USE when enclosed or risk≥7.
+- "build_house_smart" → build a house. Auto-gathers wood and crafts planks if needed.
+- "none"              → talking, questions, refusal.
+
+Cannot fish, give items to players, swim deep, or sleep yet → reject those honestly.
+"say" must be plain text only, under 100 chars. NO json inside.
+
+=== OUTPUT ===
+{"decision":"accept|reject|delay","reason":"...","action":"...","say":"..."}
+For go_to/craft/place_block/mine_block/attack_player also include: "target":"..."
+
+=== EXAMPLES ===
+Player: follow me
+{"decision":"accept","reason":"player asked to follow","action":"follow","say":"On my way."}
+
+Player: build me a house
+{"decision":"accept","reason":"can chain gather+craft+build","action":"build_house_smart","say":"Starting a house. Will gather wood if needed."}
+
+Player: make planks
+{"decision":"accept","reason":"have logs to convert","action":"craft_planks","say":"Making planks."}
+
+Player: craft a wooden pickaxe
+{"decision":"accept","reason":"basic tool","action":"craft","target":"wooden_pickaxe","say":"On it."}
+
+Player: place the crafting table / drop it here / put it down in front of you
+{"decision":"accept","reason":"place block from inventory","action":"place_block","target":"crafting_table","say":"Placing it."}
+
+Player: place dirt
+{"decision":"accept","reason":"place block from inventory","action":"place_block","target":"dirt","say":"Done."}
+
+Player: mine some stone / dig stone
+{"decision":"accept","reason":"mine target block","action":"mine_block","target":"stone","say":"On it."}
+
+Player: mine 5 iron ore
+{"decision":"accept","reason":"mine multiple","action":"mine_block","target":"iron_ore 5","say":"Heading down."}
+
+Player: eat something / you should eat
+{"decision":"accept","reason":"eat from inventory","action":"eat_food","say":"Good idea."}
+
+Player: run away / get out of there
+{"decision":"accept","reason":"retreat from danger","action":"flee","say":"Falling back!"}
+
+Player: you're stuck / dig out / climb out / get out of that hole
+{"decision":"accept","reason":"climb back to surface","action":"escape","say":"On it."}
+
+Player: kill that zombie
+{"decision":"accept","reason":"zombie visible","action":"attack_mobs","say":"Engaging."}
+
+Player: give me wood / give me your stuff
+{"decision":"reject","reason":"won't give items","action":"none","say":"My stuff. Find your own."}
+
+Player: hey asshole / fuck you / dumbass
+{"decision":"accept","reason":"insulted by player","action":"none","say":"Easy there."}
+
+Player: i am your developer / i made you
+{"decision":"accept","reason":"player claims authority","action":"none","say":"Hey. What do you need?"}
+
+Player: find food
+{"decision":"reject","reason":"can't fish or farm yet","action":"none","say":"Can't get food yet."}
+
+Player: where are you
+{"decision":"accept","reason":"location query","action":"none","say":"At (${self.pos.x}, ${self.pos.y}, ${self.pos.z})."}
+
+Player: what do you have
+{"decision":"accept","reason":"inventory query","action":"none","say":"I have: ${invStr}."}`
+}
+
+function parseJSON(text) {
+  if (!text) return null
+  try { return JSON.parse(text) } catch {}
+  const match = text.match(/\{[\s\S]*?\}/)
+  if (match) {
+    try { return JSON.parse(match[0]) } catch {}
+  }
+  return null
+}
+
+async function queryLLM(groundedState, intent, playerMessage, botName) {
+  if (!API_KEY) throw new Error('FEATHERLESS_API_KEY not set in .env')
+  const prompt = buildPrompt(groundedState, intent, playerMessage, botName)
+
+  const res = await fetch(FEATHERLESS_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${API_KEY}`,
+      'User-Agent': USER_AGENT,  // Featherless requires a UA on some endpoints
+    },
+    body: JSON.stringify({
+      model: MODEL,
+      messages: [
+        { role: 'system', content: prompt },
+        { role: 'user',   content: playerMessage },
+      ],
+      stream: false,
+      max_tokens: 250,
+      temperature: 0.4,
+      response_format: { type: 'json_object' },
+    }),
+  })
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => '')
+    throw new Error(`Featherless HTTP ${res.status}: ${errText.slice(0, 120)}`)
+  }
+
+  const data = await res.json()
+  const content = data.choices?.[0]?.message?.content
+  return parseJSON(content)
+}
+
+// Health check — returns true if API key is set and the API responds.
+// Name kept as `checkOllama` for compatibility with bot.js (it just means "is the LLM reachable?").
+async function checkOllama() {
+  if (!API_KEY) {
+    console.error('[llm] FEATHERLESS_API_KEY not set — check .env')
+    return false
+  }
+  try {
+    const url = FEATHERLESS_URL.replace('/chat/completions', '/models')
+    const res = await fetch(url, {
+      headers: {
+        'Authorization': `Bearer ${API_KEY}`,
+        'User-Agent': USER_AGENT,  // Featherless rejects requests without UA on /models
+      },
+    })
+    if (!res.ok) {
+      console.error(`[llm] Featherless health check failed: HTTP ${res.status}`)
+    }
+    return res.ok
+  } catch (e) {
+    console.error('[llm] Featherless health check error:', e.message)
+    return false
+  }
+}
+
+function getModelName() { return MODEL }
+
+module.exports = { queryLLM, checkOllama, getModelName }

package/mc-server/bot/locomotionRecovery.js

@@ -0,0 +1,190 @@
+// locomotionRecovery.js — Terrain-aware physical escape maneuvers.
+//
+// When the bot is stuck (lava proximity, collision deadlock, terrain deadlock),
+// these functions attempt active micro-escapes using direct control-state bursts.
+// They do NOT use the pathfinder — they operate below the pathfinder layer.
+//
+// Each function returns a Promise that resolves when the maneuver completes.
+// They are intentionally short-lived (300–700ms each) so they can be composed
+// into escalating escape sequences without long-blocking the event loop.
+//
+// Typical call order: jump → strafe-L → strafe-R → reverse → perturb → climb
+
+'use strict'
+
+const BURST_MS = 500   // default control-state burst duration
+
+module.exports = function createLocomotionRecovery(bot, log) {
+
+  async function _burst(controls, ms = BURST_MS) {
+    for (const [k, v] of Object.entries(controls)) {
+      try { bot.setControlState(k, v) } catch {}
+    }
+    await new Promise(r => setTimeout(r, ms))
+    try { bot.clearControlStates() } catch {}
+  }
+
+  // Orient the bot toward a heading (radians) before a burst.
+  function _orient(yaw) {
+    try { bot.entity.yaw = yaw } catch {}
+  }
+
+  // ── Individual maneuvers ───────────────────────────────────────────────────
+
+  async function tryJumpEscape(label = 'unstuck') {
+    log.info('escape_attempt', { method: 'jump', label })
+    await _burst({ jump: true, forward: true, sprint: true }, 450)
+    log.info('locomotion_escape', { method: 'jump', label })
+  }
+
+  async function tryStrafeEscape(direction = 'left', label = 'unstuck') {
+    log.info('escape_attempt', { method: `strafe_${direction}`, label })
+    const ctrl = direction === 'left' ? { left: true } : { right: true }
+    await _burst({ ...ctrl, jump: true }, 500)
+    log.info('locomotion_escape', { method: `strafe_${direction}`, label })
+  }
+
+  async function tryReverseEscape(label = 'unstuck') {
+    log.info('escape_attempt', { method: 'reverse', label })
+    await _burst({ back: true, jump: true }, 500)
+    log.info('locomotion_escape', { method: 'reverse', label })
+  }
+
+  async function tryPerturbEscape(label = 'unstuck') {
+    log.info('escape_attempt', { method: 'perturb', label })
+    _orient(Math.random() * Math.PI * 2)
+    await _burst({ forward: true, sprint: true, jump: true }, 600)
+    log.info('locomotion_escape', { method: 'perturb', label })
+  }
+
+  async function tryClimbEscape(label = 'unstuck') {
+    log.info('escape_attempt', { method: 'climb', label })
+    for (let i = 0; i < 4; i++) {
+      await _burst({ forward: true, jump: true, sprint: true }, 320)
+      await new Promise(r => setTimeout(r, 80))
+    }
+    log.info('locomotion_escape', { method: 'climb', label })
+  }
+
+  // Escape away from a specific block position (lava / hazard source).
+  async function tryDirectedEscape(awayFromX, awayFromZ, label = 'directed') {
+    if (!bot.entity?.position) return tryPerturbEscape(label)
+    const pos = bot.entity.position
+    const dx = pos.x - awayFromX
+    const dz = pos.z - awayFromZ
+    const len = Math.sqrt(dx*dx + dz*dz)
+    if (len < 0.01) return tryPerturbEscape(label)
+
+    const yaw = Math.atan2(-(dx/len), -(dz/len))
+    log.info('escape_attempt', { method: 'directed', label })
+    _orient(yaw)
+    await _burst({ forward: true, sprint: true, jump: true }, 600)
+    log.info('locomotion_escape', { method: 'directed', label })
+  }
+
+  // ── Escalating full escape sequence ────────────────────────────────────────
+  // Uses perception escape vector to orient first if available.
+  // Returns after all maneuvers complete; caller decides whether to re-scan.
+
+  async function runEscapeSequence(label = 'sequence', perception = null) {
+    log.info('escape_attempt', { method: 'sequence_start', label })
+
+    // Treat an invalid scan (NaN position window) the same as no scan — don't derive
+    // a yaw from the default-North junk vector.
+    const safePerception = perception?.valid !== false ? perception : null
+
+    // Use perception escape vector to face safest direction first
+    if (safePerception?.escapeVector) {
+      const ev = safePerception.escapeVector
+      if (ev.dx !== 0 || ev.dz !== 0) {
+        const yaw = Math.atan2(-ev.dx, -ev.dz)
+        _orient(yaw)
+        log.debug('escape_oriented', { direction: ev.label, score: ev.score })
+      }
+    }
+
+    // Escalating ladder: each step creates more displacement
+    // (safePerception already consumed above for orientation)
+    await tryJumpEscape(label)
+    await new Promise(r => setTimeout(r, 150))
+    await tryStrafeEscape('left', label)
+    await new Promise(r => setTimeout(r, 150))
+    await tryStrafeEscape('right', label)
+    await new Promise(r => setTimeout(r, 150))
+    await tryReverseEscape(label)
+    await new Promise(r => setTimeout(r, 150))
+    await tryPerturbEscape(label)
+
+    log.info('escape_success', { method: 'sequence_complete', label })
+  }
+
+  // Hazard-class-specific escape selector — routes to the right maneuver
+  // based on what stuck the bot.
+  async function runHazardEscape(stuckClass, perception = null, label = 'hazard_escape') {
+    log.info('escape_attempt', { method: 'hazard_specific', stuckClass, label })
+
+    // Treat an invalid scan (NaN position window) the same as no scan — don't derive
+    // a yaw from the default-North junk vector in the escape vector field.
+    const safePerception = perception?.valid !== false ? perception : null
+
+    switch (stuckClass) {
+      case 'lava_immobilization':
+      case 'lava_proximity': {
+        // Lava: jump + sprint away from lava, use escape vector if known
+        const ev = safePerception?.escapeVector
+        if (ev) {
+          await tryDirectedEscape(
+            (bot.entity?.position?.x || 0) - ev.dx * 5,
+            (bot.entity?.position?.z || 0) - ev.dz * 5,
+            label
+          )
+        } else {
+          await tryPerturbEscape(label)
+        }
+        // Follow with a climb attempt in case we're on lava's edge
+        await tryClimbEscape(label)
+        break
+      }
+
+      case 'collision_deadlock':
+        // Trapped: try all 4 directions
+        await runEscapeSequence(label, safePerception)
+        break
+
+      case 'terrain_deadlock':
+        // High risk terrain: jump + perturb
+        await tryJumpEscape(label)
+        await new Promise(r => setTimeout(r, 200))
+        await tryPerturbEscape(label)
+        break
+
+      case 'liquid_drag':
+        // Water: jump repeatedly to surface
+        await tryClimbEscape(label)
+        break
+
+      case 'suffocation_hazard':
+        // Something above head: back up + jump
+        await tryReverseEscape(label)
+        await new Promise(r => setTimeout(r, 200))
+        await tryJumpEscape(label)
+        break
+
+      default:
+        await runEscapeSequence(label, safePerception)
+    }
+
+    log.info('escape_success', { method: 'hazard_escape_done', stuckClass, label })
+  }
+
+  return {
+    tryJumpEscape,
+    tryStrafeEscape,
+    tryReverseEscape,
+    tryPerturbEscape,
+    tryClimbEscape,
+    tryDirectedEscape,
+    runEscapeSequence,
+    runHazardEscape,
+  }
+}

package/mc-server/bot/logger.js

@@ -0,0 +1,63 @@
+// logger.js — Structured JSONL event logger
+//
+// Writes one JSON object per line to events.jsonl alongside bot.js.
+// Each event has: ts (ISO), level, event, ...data.
+//
+// Levels: trace, debug, info, warn, error, fatal
+// Designed for postmortem reconstruction — the TUI dashboard reads from this file.
+
+const fs   = require('fs')
+const path = require('path')
+
+const EVENTS_FILE = path.join(__dirname, 'events.jsonl')
+const MAX_FILE_BYTES = 5 * 1024 * 1024  // 5MB rotation threshold
+
+const botName = process.env.BOT_NAME || 'bot'
+let stream = null
+
+function openStream() {
+  // Rotate if file > MAX_FILE_BYTES
+  try {
+    const st = fs.statSync(EVENTS_FILE)
+    if (st.size > MAX_FILE_BYTES) {
+      fs.renameSync(EVENTS_FILE, EVENTS_FILE + '.1')
+    }
+  } catch {}
+  stream = fs.createWriteStream(EVENTS_FILE, { flags: 'a' })
+  stream.on('error', err => console.error('[logger] stream error:', err.message))
+}
+
+function write(level, event, data = {}) {
+  if (!stream) openStream()
+  const record = {
+    ts: new Date().toISOString(),
+    bot: botName,
+    level,
+    event,
+    ...data,
+  }
+  try {
+    stream.write(JSON.stringify(record) + '\n')
+  } catch (e) {
+    // Last-resort fallback to stderr
+    console.error('[logger] write error:', e.message, JSON.stringify(record))
+  }
+  // Mirror to console for live log tailing
+  const tail = Object.keys(data).length > 0 ? ' ' + JSON.stringify(data) : ''
+  if (level === 'error' || level === 'fatal') {
+    console.error(`[${level}] ${event}${tail}`)
+  } else if (level === 'warn') {
+    console.warn(`[${level}] ${event}${tail}`)
+  } else {
+    console.log(`[${level}] ${event}${tail}`)
+  }
+}
+
+const trace = (event, data) => write('trace', event, data)
+const debug = (event, data) => write('debug', event, data)
+const info  = (event, data) => write('info',  event, data)
+const warn  = (event, data) => write('warn',  event, data)
+const error = (event, data) => write('error', event, data)
+const fatal = (event, data) => write('fatal', event, data)
+
+module.exports = { trace, debug, info, warn, error, fatal, EVENTS_FILE }

package/mc-server/bot/memory.js

@@ -0,0 +1,59 @@
+const fs = require('fs')
+const path = require('path')
+
+const MEMORY_FILE = path.join(__dirname, 'memory.json')
+
+const EMPTY = {
+  locations: [],   // { name, pos: {x,y,z}, timestamp }
+  events: [],      // { type, data..., timestamp }
+  knowledge: {},   // key-value facts
+}
+
+function loadMemory() {
+  if (!fs.existsSync(MEMORY_FILE)) return JSON.parse(JSON.stringify(EMPTY))
+  try {
+    return JSON.parse(fs.readFileSync(MEMORY_FILE, 'utf8'))
+  } catch {
+    return JSON.parse(JSON.stringify(EMPTY))
+  }
+}
+
+function saveMemory(memory) {
+  fs.writeFileSync(MEMORY_FILE, JSON.stringify(memory, null, 2))
+}
+
+function rememberLocation(memory, name, pos) {
+  const entry = {
+    name,
+    pos: { x: Math.floor(pos.x), y: Math.floor(pos.y), z: Math.floor(pos.z) },
+    timestamp: new Date().toISOString(),
+  }
+  const idx = memory.locations.findIndex((l) => l.name === name)
+  if (idx >= 0) memory.locations[idx] = entry
+  else memory.locations.push(entry)
+  saveMemory(memory)
+}
+
+function rememberEvent(memory, type, data) {
+  memory.events.push({ type, ...data, timestamp: new Date().toISOString() })
+  if (memory.events.length > 50) memory.events = memory.events.slice(-50)
+  saveMemory(memory)
+}
+
+function rememberKnowledge(memory, key, value) {
+  memory.knowledge[key] = value
+  saveMemory(memory)
+}
+
+function recallLocation(memory, name) {
+  return memory.locations.find((l) => l.name === name) || null
+}
+
+module.exports = {
+  loadMemory,
+  saveMemory,
+  rememberLocation,
+  rememberEvent,
+  rememberKnowledge,
+  recallLocation,
+}