rust-kgdb 0.5.12 → 0.6.0

package/hypermind-agent.js

@@ -488,6 +488,1189 @@ class WasmSandbox {
   }
 }
 
+// ============================================================================
+// MEMORY LAYER (GraphDB-Powered Agent Memory System)
+// ============================================================================
+
+/**
+ * AgentState - Lifecycle states for agent runtime
+ */
+const AgentState = {
+  CREATED: 'CREATED',
+  READY: 'READY',
+  RUNNING: 'RUNNING',
+  PAUSED: 'PAUSED',
+  COMPLETED: 'COMPLETED',
+  FAILED: 'FAILED'
+}
+
+/**
+ * AgentRuntime - Core agent identity and state management
+ *
+ * Provides:
+ * - Unique agent identity (UUID)
+ * - Lifecycle state management
+ * - Memory layer orchestration
+ * - Execution context tracking
+ */
+class AgentRuntime {
+  constructor(config = {}) {
+    // Agent Identity
+    this.id = config.id || `agent_${crypto.randomUUID()}`
+    this.name = config.name || 'unnamed-agent'
+    this.version = config.version || '1.0.0'
+    this.createdAt = new Date().toISOString()
+
+    // State Management
+    this.state = AgentState.CREATED
+    this.stateHistory = [{
+      state: AgentState.CREATED,
+      timestamp: this.createdAt,
+      reason: 'Agent initialized'
+    }]
+
+    // Memory Configuration
+    this.memoryConfig = {
+      workingMemoryCapacity: config.workingMemoryCapacity || 100,
+      episodicRetentionDays: config.episodicRetentionDays || 30,
+      retrievalWeights: config.retrievalWeights || {
+        recency: 0.3,    // α - time decay
+        relevance: 0.5,  // β - semantic similarity
+        importance: 0.2  // γ - access frequency
+      },
+      recencyDecayRate: config.recencyDecayRate || 0.995 // per hour
+    }
+
+    // Execution Context
+    this.currentExecution = null
+    this.executionCount = 0
+    this.lastActiveAt = this.createdAt
+
+    // Metrics
+    this.metrics = {
+      totalExecutions: 0,
+      successfulExecutions: 0,
+      failedExecutions: 0,
+      totalMemoryRetrievals: 0,
+      avgExecutionTimeMs: 0
+    }
+  }
+
+  /**
+   * Transition agent to a new state
+   */
+  transitionTo(newState, reason = '') {
+    const validTransitions = {
+      [AgentState.CREATED]: [AgentState.READY],
+      [AgentState.READY]: [AgentState.RUNNING, AgentState.PAUSED],
+      [AgentState.RUNNING]: [AgentState.READY, AgentState.COMPLETED, AgentState.FAILED, AgentState.PAUSED],
+      [AgentState.PAUSED]: [AgentState.READY, AgentState.RUNNING],
+      [AgentState.COMPLETED]: [AgentState.READY],
+      [AgentState.FAILED]: [AgentState.READY]
+    }
+
+    if (!validTransitions[this.state]?.includes(newState)) {
+      throw new Error(`Invalid state transition: ${this.state} -> ${newState}`)
+    }
+
+    this.state = newState
+    this.stateHistory.push({
+      state: newState,
+      timestamp: new Date().toISOString(),
+      reason
+    })
+    this.lastActiveAt = new Date().toISOString()
+
+    return this
+  }
+
+  /**
+   * Mark agent as ready for execution
+   */
+  ready() {
+    return this.transitionTo(AgentState.READY, 'Agent initialized and ready')
+  }
+
+  /**
+   * Start an execution
+   */
+  startExecution(prompt) {
+    this.transitionTo(AgentState.RUNNING, `Starting execution: ${prompt.slice(0, 50)}...`)
+    this.currentExecution = {
+      id: `exec_${Date.now()}_${crypto.randomUUID().slice(0, 8)}`,
+      prompt,
+      startTime: Date.now(),
+      steps: []
+    }
+    this.executionCount++
+    return this.currentExecution.id
+  }
+
+  /**
+   * Complete current execution
+   */
+  completeExecution(result, success = true) {
+    if (!this.currentExecution) return
+
+    this.currentExecution.endTime = Date.now()
+    this.currentExecution.durationMs = this.currentExecution.endTime - this.currentExecution.startTime
+    this.currentExecution.result = result
+    this.currentExecution.success = success
+
+    // Update metrics
+    this.metrics.totalExecutions++
+    if (success) {
+      this.metrics.successfulExecutions++
+    } else {
+      this.metrics.failedExecutions++
+    }
+    this.metrics.avgExecutionTimeMs =
+      (this.metrics.avgExecutionTimeMs * (this.metrics.totalExecutions - 1) +
+       this.currentExecution.durationMs) / this.metrics.totalExecutions
+
+    const execution = this.currentExecution
+    this.currentExecution = null
+    this.transitionTo(AgentState.READY, `Execution completed: ${success ? 'success' : 'failed'}`)
+
+    return execution
+  }
+
+  /**
+   * Get agent identity info
+   */
+  getIdentity() {
+    return {
+      id: this.id,
+      name: this.name,
+      version: this.version,
+      createdAt: this.createdAt,
+      state: this.state,
+      executionCount: this.executionCount,
+      lastActiveAt: this.lastActiveAt
+    }
+  }
+
+  /**
+   * Get runtime metrics
+   */
+  getMetrics() {
+    return {
+      ...this.metrics,
+      uptime: Date.now() - new Date(this.createdAt).getTime(),
+      currentState: this.state
+    }
+  }
+}
+
+/**
+ * WorkingMemory - Current execution context (in-memory)
+ *
+ * Fast, ephemeral memory for the current task:
+ * - Current conversation context
+ * - Active bindings and variables
+ * - Tool execution results (recent)
+ * - Scratchpad for reasoning
+ */
+class WorkingMemory {
+  constructor(capacity = 100) {
+    this.capacity = capacity
+    this.context = []          // Current conversation/task context
+    this.bindings = new Map()  // Variable bindings
+    this.scratchpad = new Map() // Temporary reasoning space
+    this.toolResults = []      // Recent tool execution results
+    this.focus = null          // Current focus entity/topic
+  }
+
+  /**
+   * Add item to working memory context
+   */
+  addContext(item) {
+    this.context.push({
+      ...item,
+      timestamp: item.timestamp || Date.now(),
+      id: item.id !== undefined ? item.id : `ctx_${Date.now()}`
+    })
+
+    // Evict oldest if over capacity
+    while (this.context.length > this.capacity) {
+      this.context.shift()
+    }
+
+    return this
+  }
+
+  /**
+   * Set a variable binding
+   */
+  setBinding(key, value) {
+    this.bindings.set(key, {
+      value,
+      timestamp: Date.now(),
+      accessCount: 0
+    })
+    return this
+  }
+
+  /**
+   * Get a variable binding
+   */
+  getBinding(key) {
+    const binding = this.bindings.get(key)
+    if (binding) {
+      binding.accessCount++
+      return binding.value
+    }
+    return null
+  }
+
+  /**
+   * Store tool result
+   */
+  storeToolResult(toolName, args, result) {
+    this.toolResults.push({
+      tool: toolName,
+      args,
+      result,
+      timestamp: Date.now()
+    })
+
+    // Keep only recent results
+    if (this.toolResults.length > 20) {
+      this.toolResults.shift()
+    }
+
+    return this
+  }
+
+  /**
+   * Set current focus
+   */
+  setFocus(entity) {
+    this.focus = {
+      entity,
+      timestamp: Date.now()
+    }
+    return this
+  }
+
+  /**
+   * Write to scratchpad
+   */
+  scratch(key, value) {
+    this.scratchpad.set(key, value)
+    return this
+  }
+
+  /**
+   * Read from scratchpad
+   */
+  readScratch(key) {
+    return this.scratchpad.get(key)
+  }
+
+  /**
+   * Get recent context items
+   */
+  getRecentContext(limit = 10) {
+    return this.context.slice(-limit)
+  }
+
+  /**
+   * Clear working memory
+   */
+  clear() {
+    this.context = []
+    this.bindings.clear()
+    this.scratchpad.clear()
+    this.toolResults = []
+    this.focus = null
+    return this
+  }
+
+  /**
+   * Export working memory state
+   */
+  export() {
+    return {
+      context: this.context,
+      bindings: Object.fromEntries(this.bindings),
+      scratchpad: Object.fromEntries(this.scratchpad),
+      toolResults: this.toolResults,
+      focus: this.focus
+    }
+  }
+}
+
+/**
+ * EpisodicMemory - Execution history stored in GraphDB
+ *
+ * Persistent memory of agent executions:
+ * - Past prompts and responses
+ * - Tool invocation history
+ * - Success/failure outcomes
+ * - Temporal relationships
+ */
+class EpisodicMemory {
+  constructor(graphDb, namespace = 'http://hypermind.ai/episodic/') {
+    this.graphDb = graphDb
+    this.namespace = namespace
+    this.episodeCount = 0
+  }
+
+  /**
+   * Store an execution episode
+   */
+  async storeEpisode(agentId, execution) {
+    const episodeUri = `${this.namespace}episode/${execution.id}`
+    const timestamp = new Date().toISOString()
+
+    // Build episode triples
+    const triples = `
+      @prefix ep: <${this.namespace}> .
+      @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+      @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+
+      <${episodeUri}> rdf:type ep:Episode ;
+        ep:agentId "${agentId}" ;
+        ep:executionId "${execution.id}" ;
+        ep:prompt "${this._escapeForTtl(execution.prompt)}" ;
+        ep:timestamp "${timestamp}"^^xsd:dateTime ;
+        ep:durationMs "${execution.durationMs || 0}"^^xsd:integer ;
+        ep:success "${execution.success}"^^xsd:boolean .
+    `
+
+    // Store in GraphDB
+    if (this.graphDb && typeof this.graphDb.loadTtl === 'function') {
+      await this.graphDb.loadTtl(triples, `${this.namespace}episodes`)
+    }
+
+    this.episodeCount++
+
+    return {
+      episodeUri,
+      timestamp,
+      stored: true
+    }
+  }
+
+  /**
+   * Store a tool invocation within an episode
+   */
+  async storeToolInvocation(episodeId, toolName, args, result, success) {
+    const invocationUri = `${this.namespace}invocation/${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+
+    const triples = `
+      @prefix ep: <${this.namespace}> .
+      @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+      <${invocationUri}> a ep:ToolInvocation ;
+        ep:episode <${this.namespace}episode/${episodeId}> ;
+        ep:tool "${toolName}" ;
+        ep:timestamp "${new Date().toISOString()}"^^xsd:dateTime ;
+        ep:success "${success}"^^xsd:boolean .
+    `
+
+    if (this.graphDb && typeof this.graphDb.loadTtl === 'function') {
+      await this.graphDb.loadTtl(triples, `${this.namespace}invocations`)
+    }
+
+    return invocationUri
+  }
+
+  /**
+   * Retrieve episodes for an agent
+   */
+  async getEpisodes(agentId, options = {}) {
+    const limit = options.limit || 20
+    const since = options.since || null
+
+    let query = `
+      PREFIX ep: <${this.namespace}>
+      PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+
+      SELECT ?episode ?prompt ?timestamp ?durationMs ?success
+      WHERE {
+        ?episode a ep:Episode ;
+          ep:agentId "${agentId}" ;
+          ep:prompt ?prompt ;
+          ep:timestamp ?timestamp ;
+          ep:durationMs ?durationMs ;
+          ep:success ?success .
+        ${since ? `FILTER(?timestamp > "${since}"^^xsd:dateTime)` : ''}
+      }
+      ORDER BY DESC(?timestamp)
+      LIMIT ${limit}
+    `
+
+    if (this.graphDb && typeof this.graphDb.querySelect === 'function') {
+      try {
+        const results = await this.graphDb.querySelect(query)
+        return results.map(r => ({
+          episode: r.bindings?.episode || r.episode,
+          prompt: r.bindings?.prompt || r.prompt,
+          timestamp: r.bindings?.timestamp || r.timestamp,
+          durationMs: parseInt(r.bindings?.durationMs || r.durationMs || '0'),
+          success: (r.bindings?.success || r.success) === 'true'
+        }))
+      } catch (e) {
+        // GraphDB not available, return empty
+        return []
+      }
+    }
+
+    return []
+  }
+
+  /**
+   * Get episodes similar to a prompt (using embeddings if available)
+   */
+  async getSimilarEpisodes(prompt, k = 5, threshold = 0.7) {
+    // This will be enhanced when EmbeddingService is integrated
+    // For now, return recent episodes as fallback
+    return this.getEpisodes('*', { limit: k })
+  }
+
+  /**
+   * Calculate recency score with exponential decay
+   */
+  calculateRecencyScore(timestamp, decayRate = 0.995) {
+    const hoursElapsed = (Date.now() - new Date(timestamp).getTime()) / (1000 * 60 * 60)
+    return Math.pow(decayRate, hoursElapsed)
+  }
+
+  /**
+   * Escape string for Turtle format
+   */
+  _escapeForTtl(str) {
+    if (!str) return ''
+    return str
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n')
+      .replace(/\r/g, '\\r')
+      .replace(/\t/g, '\\t')
+  }
+
+  /**
+   * Get episode count
+   */
+  getEpisodeCount() {
+    return this.episodeCount
+  }
+}
+
+/**
+ * LongTermMemory - Source-of-truth Knowledge Graph
+ *
+ * Read-only access to the ingestion graph (source of truth):
+ * - Domain ontologies and schemas
+ * - Factual knowledge from data ingestion
+ * - Business rules and constraints
+ * - Clear separation from agent memory
+ */
+class LongTermMemory {
+  constructor(graphDb, config = {}) {
+    this.graphDb = graphDb
+    this.sourceGraphUri = config.sourceGraphUri || 'http://hypermind.ai/source/'
+    this.agentGraphUri = config.agentGraphUri || 'http://hypermind.ai/agent/'
+    this.readOnly = config.readOnly !== false // Default to read-only
+    this.accessLog = []
+  }
+
+  /**
+   * Query the source-of-truth graph (read-only)
+   */
+  async querySource(sparql) {
+    this._logAccess('query', sparql)
+
+    // Ensure query targets source graph
+    const graphQuery = sparql.includes('FROM') ? sparql :
+      sparql.replace('WHERE', `FROM <${this.sourceGraphUri}> WHERE`)
+
+    if (this.graphDb && typeof this.graphDb.querySelect === 'function') {
+      try {
+        return await this.graphDb.querySelect(graphQuery)
+      } catch (e) {
+        return []
+      }
+    }
+
+    return []
+  }
+
+  /**
+   * Get entity facts from source graph
+   */
+  async getEntityFacts(entityUri, limit = 50) {
+    const query = `
+      SELECT ?p ?o WHERE {
+        <${entityUri}> ?p ?o .
+      } LIMIT ${limit}
+    `
+    return this.querySource(query)
+  }
+
+  /**
+   * Get entities by type from source graph
+   */
+  async getEntitiesByType(typeUri, limit = 100) {
+    const query = `
+      PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+      SELECT ?entity WHERE {
+        ?entity rdf:type <${typeUri}> .
+      } LIMIT ${limit}
+    `
+    return this.querySource(query)
+  }
+
+  /**
+   * Get related entities (1-hop neighbors)
+   */
+  async getRelatedEntities(entityUri, direction = 'both') {
+    let query
+    if (direction === 'out') {
+      query = `SELECT ?p ?target WHERE { <${entityUri}> ?p ?target . FILTER(isIRI(?target)) }`
+    } else if (direction === 'in') {
+      query = `SELECT ?source ?p WHERE { ?source ?p <${entityUri}> . FILTER(isIRI(?source)) }`
+    } else {
+      query = `
+        SELECT ?direction ?p ?entity WHERE {
+          { <${entityUri}> ?p ?entity . BIND("out" AS ?direction) FILTER(isIRI(?entity)) }
+          UNION
+          { ?entity ?p <${entityUri}> . BIND("in" AS ?direction) FILTER(isIRI(?entity)) }
+        }
+      `
+    }
+    return this.querySource(query)
+  }
+
+  /**
+   * Get schema/ontology information
+   */
+  async getSchema(prefix = null) {
+    const query = `
+      PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+      PREFIX owl: <http://www.w3.org/2002/07/owl#>
+
+      SELECT ?class ?property ?domain ?range WHERE {
+        {
+          ?class a owl:Class .
+        } UNION {
+          ?property a owl:ObjectProperty .
+          OPTIONAL { ?property rdfs:domain ?domain }
+          OPTIONAL { ?property rdfs:range ?range }
+        } UNION {
+          ?property a owl:DatatypeProperty .
+          OPTIONAL { ?property rdfs:domain ?domain }
+          OPTIONAL { ?property rdfs:range ?range }
+        }
+      }
+    `
+    return this.querySource(query)
+  }
+
+  /**
+   * Log access for audit
+   */
+  _logAccess(operation, details) {
+    this.accessLog.push({
+      operation,
+      details: details.slice(0, 200),
+      timestamp: new Date().toISOString()
+    })
+
+    // Keep only recent access log entries
+    if (this.accessLog.length > 1000) {
+      this.accessLog = this.accessLog.slice(-500)
+    }
+  }
+
+  /**
+   * Get access log
+   */
+  getAccessLog(limit = 100) {
+    return this.accessLog.slice(-limit)
+  }
+
+  /**
+   * Get graph URIs
+   */
+  getGraphUris() {
+    return {
+      source: this.sourceGraphUri,
+      agent: this.agentGraphUri,
+      separation: 'Source graph is read-only truth from ingestion. Agent graph is agent-writable memory.'
+    }
+  }
+}
+
+/**
+ * MemoryManager - Unified memory retrieval with weighted scoring
+ *
+ * Orchestrates all memory layers with intelligent retrieval:
+ * - Score = α × Recency + β × Relevance + γ × Importance
+ * - α = 0.3 (time decay), β = 0.5 (semantic similarity), γ = 0.2 (access frequency)
+ */
+class MemoryManager {
+  constructor(runtime, config = {}) {
+    this.runtime = runtime
+
+    // Initialize memory layers
+    this.working = new WorkingMemory(config.workingCapacity || 100)
+    this.episodic = new EpisodicMemory(config.graphDb, config.episodicNamespace)
+    this.longTerm = new LongTermMemory(config.graphDb, {
+      sourceGraphUri: config.sourceGraphUri,
+      agentGraphUri: config.agentGraphUri
+    })
+
+    // Retrieval weights
+    this.weights = config.weights || {
+      recency: 0.3,
+      relevance: 0.5,
+      importance: 0.2
+    }
+
+    // Access tracking for importance scoring
+    this.accessCounts = new Map()
+    this.retrievalHistory = []
+  }
+
+  /**
+   * Unified memory retrieval with weighted scoring
+   */
+  async retrieve(query, options = {}) {
+    const results = {
+      working: [],
+      episodic: [],
+      longTerm: [],
+      combined: []
+    }
+
+    // 1. Working Memory (always fast, in-memory)
+    results.working = this._searchWorkingMemory(query)
+
+    // 2. Episodic Memory (past executions)
+    if (options.includeEpisodic !== false) {
+      const episodes = await this.episodic.getEpisodes(this.runtime.id, { limit: 20 })
+      results.episodic = this._scoreEpisodicResults(episodes, query)
+    }
+
+    // 3. Long-term Memory (source of truth)
+    if (options.includeLongTerm !== false && options.entityUri) {
+      const facts = await this.longTerm.getEntityFacts(options.entityUri)
+      results.longTerm = facts.map(f => ({
+        ...f,
+        score: 0.8, // Facts from source of truth have high base score
+        source: 'longTerm'
+      }))
+    }
+
+    // 4. Combine and rank
+    results.combined = this._combineAndRank([
+      ...results.working.map(r => ({ ...r, source: 'working' })),
+      ...results.episodic,
+      ...results.longTerm
+    ])
+
+    // Track retrieval
+    this._trackRetrieval(query, results)
+    this.runtime.metrics.totalMemoryRetrievals++
+
+    return results
+  }
+
+  /**
+   * Search working memory
+   */
+  _searchWorkingMemory(query) {
+    const results = []
+    const queryLower = query.toLowerCase()
+
+    // Search context
+    for (const ctx of this.working.context) {
+      const content = JSON.stringify(ctx).toLowerCase()
+      if (content.includes(queryLower)) {
+        results.push({
+          type: 'context',
+          data: ctx,
+          score: this._calculateScore(ctx.timestamp, 0.8, this._getAccessCount(ctx.id))
+        })
+      }
+    }
+
+    // Search tool results
+    for (const tr of this.working.toolResults) {
+      if (tr.tool.toLowerCase().includes(queryLower) ||
+          JSON.stringify(tr.result).toLowerCase().includes(queryLower)) {
+        results.push({
+          type: 'toolResult',
+          data: tr,
+          score: this._calculateScore(tr.timestamp, 0.7, 1)
+        })
+      }
+    }
+
+    return results.sort((a, b) => b.score - a.score)
+  }
+
+  /**
+   * Score episodic results
+   */
+  _scoreEpisodicResults(episodes, query) {
+    return episodes.map(ep => {
+      const recencyScore = this.episodic.calculateRecencyScore(ep.timestamp)
+      const relevanceScore = this._calculateRelevance(ep.prompt, query)
+      const importanceScore = this._getAccessCount(`ep_${ep.episode}`) / 10
+
+      return {
+        ...ep,
+        source: 'episodic',
+        score: this._calculateScore(ep.timestamp, relevanceScore, importanceScore)
+      }
+    }).sort((a, b) => b.score - a.score)
+  }
+
+  /**
+   * Calculate weighted score
+   */
+  _calculateScore(timestamp, relevance, accessCount) {
+    const recency = this.episodic.calculateRecencyScore(timestamp)
+    const importance = Math.min(accessCount / 10, 1)
+
+    return (
+      this.weights.recency * recency +
+      this.weights.relevance * relevance +
+      this.weights.importance * importance
+    )
+  }
+
+  /**
+   * Calculate text relevance (simple term overlap)
+   */
+  _calculateRelevance(text1, text2) {
+    if (!text1 || !text2) return 0
+    const words1 = new Set(text1.toLowerCase().split(/\s+/))
+    const words2 = new Set(text2.toLowerCase().split(/\s+/))
+    const intersection = [...words1].filter(w => words2.has(w))
+    return intersection.length / Math.max(words1.size, words2.size)
+  }
+
+  /**
+   * Get access count for importance scoring
+   */
+  _getAccessCount(id) {
+    return this.accessCounts.get(id) || 0
+  }
+
+  /**
+   * Increment access count
+   */
+  _incrementAccess(id) {
+    this.accessCounts.set(id, (this.accessCounts.get(id) || 0) + 1)
+  }
+
+  /**
+   * Combine and rank results from all memory layers
+   */
+  _combineAndRank(results) {
+    return results
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 20) // Top 20 results
+  }
+
+  /**
+   * Track retrieval for analytics
+   */
+  _trackRetrieval(query, results) {
+    this.retrievalHistory.push({
+      query,
+      timestamp: Date.now(),
+      counts: {
+        working: results.working.length,
+        episodic: results.episodic.length,
+        longTerm: results.longTerm.length
+      }
+    })
+
+    // Increment access counts for returned results
+    for (const r of results.combined) {
+      if (r.data?.id) {
+        this._incrementAccess(r.data.id)
+      }
+    }
+  }
+
+  /**
+   * Store execution in episodic memory
+   */
+  async storeExecution(execution) {
+    return this.episodic.storeEpisode(this.runtime.id, execution)
+  }
+
+  /**
+   * Add to working memory
+   */
+  addToWorking(item) {
+    this.working.addContext(item)
+    return this
+  }
+
+  /**
+   * Get memory statistics
+   */
+  getStats() {
+    return {
+      working: {
+        contextSize: this.working.context.length,
+        bindingsCount: this.working.bindings.size,
+        toolResultsCount: this.working.toolResults.length
+      },
+      episodic: {
+        episodeCount: this.episodic.getEpisodeCount()
+      },
+      longTerm: {
+        accessLogSize: this.longTerm.accessLog.length
+      },
+      retrieval: {
+        totalRetrievals: this.retrievalHistory.length,
+        uniqueAccessedItems: this.accessCounts.size
+      },
+      weights: this.weights
+    }
+  }
+
+  /**
+   * Clear working memory (episodic and long-term persist)
+   */
+  clearWorking() {
+    this.working.clear()
+    return this
+  }
+}
+
+// ============================================================================
+// GOVERNANCE LAYER (Policy Engine & Capability Grants)
+// ============================================================================
+
+/**
+ * GovernancePolicy - Defines access control and behavioral policies
+ */
+class GovernancePolicy {
+  constructor(config = {}) {
+    this.name = config.name || 'default-policy'
+    this.version = config.version || '1.0.0'
+
+    // Capability definitions
+    this.capabilities = new Set(config.capabilities || [
+      'ReadKG',
+      'WriteKG',
+      'ExecuteTool',
+      'AccessMemory',
+      'ModifyMemory'
+    ])
+
+    // Resource limits
+    this.limits = config.limits || {
+      maxExecutionTimeMs: 60000,
+      maxMemoryMB: 256,
+      maxToolCalls: 100,
+      maxGraphQueries: 1000
+    }
+
+    // Audit requirements
+    this.audit = config.audit || {
+      logAllToolCalls: true,
+      logMemoryAccess: true,
+      logGraphQueries: true,
+      retentionDays: 90
+    }
+
+    // Behavioral constraints
+    this.constraints = config.constraints || {
+      allowExternalApi: false,
+      allowFileAccess: false,
+      requireApprovalForWrites: false
+    }
+  }
+
+  /**
+   * Check if capability is granted
+   */
+  hasCapability(capability) {
+    return this.capabilities.has(capability)
+  }
+
+  /**
+   * Grant a capability
+   */
+  grantCapability(capability) {
+    this.capabilities.add(capability)
+    return this
+  }
+
+  /**
+   * Revoke a capability
+   */
+  revokeCapability(capability) {
+    this.capabilities.delete(capability)
+    return this
+  }
+
+  /**
+   * Check resource limit
+   */
+  checkLimit(resource, current) {
+    const limit = this.limits[resource]
+    return limit === undefined || current <= limit
+  }
+
+  /**
+   * Export policy as JSON
+   */
+  export() {
+    return {
+      name: this.name,
+      version: this.version,
+      capabilities: [...this.capabilities],
+      limits: this.limits,
+      audit: this.audit,
+      constraints: this.constraints
+    }
+  }
+}
+
+/**
+ * GovernanceEngine - Enforces policies and manages capability grants
+ */
+class GovernanceEngine {
+  constructor(policy = null) {
+    this.policy = policy || new GovernancePolicy()
+    this.auditLog = []
+    this.denials = []
+  }
+
+  /**
+   * Authorize an action
+   */
+  authorize(action, context = {}) {
+    const result = {
+      allowed: false,
+      reason: '',
+      capability: action.capability,
+      timestamp: new Date().toISOString()
+    }
+
+    // Check capability
+    if (action.capability && !this.policy.hasCapability(action.capability)) {
+      result.reason = `Missing capability: ${action.capability}`
+      this._logDenial(action, result.reason)
+      return result
+    }
+
+    // Check resource limits
+    if (action.resource && action.current !== undefined) {
+      if (!this.policy.checkLimit(action.resource, action.current)) {
+        result.reason = `Resource limit exceeded: ${action.resource}`
+        this._logDenial(action, result.reason)
+        return result
+      }
+    }
+
+    // Check constraints
+    if (action.type === 'externalApi' && !this.policy.constraints.allowExternalApi) {
+      result.reason = 'External API access not allowed'
+      this._logDenial(action, result.reason)
+      return result
+    }
+
+    result.allowed = true
+    result.reason = 'Authorized'
+    this._logAudit(action, result)
+
+    return result
+  }
+
+  /**
+   * Log audit entry
+   */
+  _logAudit(action, result) {
+    if (this.policy.audit.logAllToolCalls ||
+        (this.policy.audit.logMemoryAccess && action.type === 'memory') ||
+        (this.policy.audit.logGraphQueries && action.type === 'graphQuery')) {
+      this.auditLog.push({
+        action,
+        result,
+        timestamp: new Date().toISOString()
+      })
+    }
+  }
+
+  /**
+   * Log denial
+   */
+  _logDenial(action, reason) {
+    this.denials.push({
+      action,
+      reason,
+      timestamp: new Date().toISOString()
+    })
+  }
+
+  /**
+   * Get audit log
+   */
+  getAuditLog(limit = 100) {
+    return this.auditLog.slice(-limit)
+  }
+
+  /**
+   * Get denials
+   */
+  getDenials(limit = 50) {
+    return this.denials.slice(-limit)
+  }
+
+  /**
+   * Update policy
+   */
+  setPolicy(policy) {
+    this.policy = policy
+    return this
+  }
+}
+
+// ============================================================================
+// SCOPE LAYER (Namespace Isolation & Resource Limits)
+// ============================================================================
+
+/**
+ * AgentScope - Defines namespace and resource boundaries for agents
+ */
+class AgentScope {
+  constructor(config = {}) {
+    this.id = config.id || `scope_${crypto.randomUUID()}`
+    this.name = config.name || 'default-scope'
+
+    // Namespace configuration
+    this.namespace = config.namespace || {
+      prefix: 'http://hypermind.ai/agent/',
+      graphUri: `http://hypermind.ai/agent/${this.id}/`,
+      allowedGraphs: ['*'], // '*' means all, or list specific graph URIs
+      deniedGraphs: []
+    }
+
+    // Resource limits
+    this.resources = {
+      maxMemoryMB: config.maxMemoryMB || 256,
+      maxExecutionTimeMs: config.maxExecutionTimeMs || 60000,
+      maxToolCalls: config.maxToolCalls || 100,
+      maxGraphQueries: config.maxGraphQueries || 1000,
+      maxEpisodes: config.maxEpisodes || 10000
+    }
+
+    // Current usage tracking
+    this.usage = {
+      memoryMB: 0,
+      executionTimeMs: 0,
+      toolCalls: 0,
+      graphQueries: 0,
+      episodes: 0
+    }
+
+    // Isolation settings
+    this.isolation = {
+      shareMemory: config.shareMemory || false,
+      shareEpisodes: config.shareEpisodes || false,
+      parentScope: config.parentScope || null
+    }
+  }
+
+  /**
+   * Check if graph access is allowed
+   */
+  isGraphAllowed(graphUri) {
+    // Check denied first
+    if (this.namespace.deniedGraphs.includes(graphUri)) {
+      return false
+    }
+
+    // Check allowed
+    if (this.namespace.allowedGraphs.includes('*')) {
+      return true
+    }
+
+    return this.namespace.allowedGraphs.some(pattern => {
+      if (pattern.endsWith('*')) {
+        return graphUri.startsWith(pattern.slice(0, -1))
+      }
+      return graphUri === pattern
+    })
+  }
+
+  /**
+   * Track resource usage
+   */
+  trackUsage(resource, amount) {
+    if (this.usage[resource] !== undefined) {
+      this.usage[resource] += amount
+    }
+    return this
+  }
+
+  /**
+   * Check if resource limit exceeded
+   */
+  isWithinLimits(resource) {
+    const limit = this.resources[`max${resource.charAt(0).toUpperCase()}${resource.slice(1)}`]
+    return limit === undefined || this.usage[resource] <= limit
+  }
+
+  /**
+   * Get remaining resources
+   */
+  getRemainingResources() {
+    const remaining = {}
+    for (const [key, limit] of Object.entries(this.resources)) {
+      // Convert maxToolCalls -> toolCalls (preserve camelCase)
+      const withoutMax = key.replace(/^max/, '')
+      const usageKey = withoutMax.charAt(0).toLowerCase() + withoutMax.slice(1)
+      remaining[usageKey] = limit - (this.usage[usageKey] || 0)
+    }
+    return remaining
+  }
+
+  /**
+   * Reset usage counters
+   */
+  resetUsage() {
+    for (const key of Object.keys(this.usage)) {
+      this.usage[key] = 0
+    }
+    return this
+  }
+
+  /**
+   * Get scoped graph URI for agent
+   */
+  getScopedGraphUri(suffix = '') {
+    return `${this.namespace.graphUri}${suffix}`
+  }
+
+  /**
+   * Export scope configuration
+   */
+  export() {
+    return {
+      id: this.id,
+      name: this.name,
+      namespace: this.namespace,
+      resources: this.resources,
+      usage: this.usage,
+      isolation: this.isolation
+    }
+  }
+}
+
 // ============================================================================
 // AGENT BUILDER (Fluent Composition Pattern)
 // ============================================================================
@@ -1547,5 +2730,20 @@ module.exports = {
   LLMPlanner,              // Natural language -> typed tool pipelines
   WasmSandbox,             // WASM sandbox with capability-based security
   AgentBuilder,            // Fluent builder for agent composition
-  ComposedAgent            // Composed agent with sandbox execution
+  ComposedAgent,           // Composed agent with sandbox execution
+
+  // Memory Layer (v0.5.13+) - GraphDB-Powered Agent Memory
+  AgentState,              // Agent lifecycle states (CREATED, READY, RUNNING, etc.)
+  AgentRuntime,            // Agent identity and state management
+  WorkingMemory,           // In-memory current context
+  EpisodicMemory,          // Execution history stored in GraphDB
+  LongTermMemory,          // Source-of-truth knowledge graph (read-only)
+  MemoryManager,           // Unified memory retrieval with weighted scoring
+
+  // Governance Layer (v0.5.13+) - Policy Engine & Capability Grants
+  GovernancePolicy,        // Access control and behavioral policies
+  GovernanceEngine,        // Policy enforcement and audit logging
+
+  // Scope Layer (v0.5.13+) - Namespace Isolation & Resource Limits
+  AgentScope               // Namespace boundaries and resource tracking
 }