kiku-agent 1.2.0 → 1.3.1

package/server/agent/memory.js

@@ -1,40 +1,52 @@
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
 import { EXPORT_DIR, KIKU_DATA_DIR, SESSION_DIR } from './appPaths.js';
 import { redactSensitiveValue } from './session.js';
-
-const MEMORY_DIR = KIKU_DATA_DIR;
-const MEMORY_FILE = path.join(MEMORY_DIR, 'long_term_memory.json');
-const SESSIONS_DIR = SESSION_DIR;
-
-
+import { HierarchicalStore } from './memory/hierarchicalStore.js';
+import { ContextAllocator } from './memory/contextAllocator.js';
+import { ReflectionWorker } from './memory/reflectionWorker.js';
+
+const MEMORY_DIR = KIKU_DATA_DIR;
+const MEMORY_FILE = path.join(MEMORY_DIR, 'long_term_memory.json');
+const SESSIONS_DIR = SESSION_DIR;
+const MAX_FACTS = 500;
+const SAVE_DEBOUNCE_MS = 400;
+
+
 export class AgentMemory {
   constructor(options = {}) {
     this.persistenceEnabled = options.persistence !== false;
     this.storageFile = options.storageFile ? path.resolve(String(options.storageFile)) : MEMORY_FILE;
-    this.facts = [];
-    this.preferences = {
-      language: null,          
-      topicsOfInterest: [],    
-      responseStyle: 'default', 
-      userSkills: [],
-      skillsEnabled: true,
-      favorites: [],
-      learnedStyles: [],
+    this.facts = [];
+    this.preferences = {
+      language: null,          
+      topicsOfInterest: [],    
+      responseStyle: 'default', 
+      userSkills: [],
+      skillsEnabled: true,
+      favorites: [],
+      learnedStyles: [],
+    };
+    this.sessions = [];         
+    this.summaries = [];       
+    this.stats = {
+      totalFacts: 0,
+      totalSessions: 0,
+      totalConsolidations: 0,
+      lastConsolidationAt: null,
+      createdAt: new Date()
     };
-    this.sessions = [];         
-    this.summaries = [];       
-    this.stats = {
-      totalFacts: 0,
-      totalSessions: 0,
-      totalConsolidations: 0,
-      lastConsolidationAt: null,
-      createdAt: new Date()
-    };
-    this._loaded = false;
-    this._storageWarningShown = false;
-    this._storageError = null;
-  }
+    this.hierarchicalStore = options.hierarchicalStore || new HierarchicalStore({ persistence: this.persistenceEnabled });
+    this.contextAllocator = new ContextAllocator({ store: this.hierarchicalStore });
+    this.reflectionWorker = new ReflectionWorker({ store: this.hierarchicalStore, memory: this });
+    this.activeRunId = options.activeRunId || null;
+    this._loaded = false;
+    this._storageWarningShown = false;
+    this._storageError = null;
+    this._saveTimer = null;
+    this._saveTimerResolve = null;
+    this._saveChain = Promise.resolve();
+  }
 
 
   async init() {
@@ -45,6 +57,7 @@ export class AgentMemory {
     try {
       await fs.mkdir(MEMORY_DIR, { recursive: true, mode: 0o700 });
       await fs.mkdir(SESSIONS_DIR, { recursive: true, mode: 0o700 });
+      await this.hierarchicalStore.init();
       this._storageError = null;
       return true;
     } catch (error) {
@@ -77,12 +90,12 @@ export class AgentMemory {
         lastAccessedAt: f.lastAccessedAt ? new Date(f.lastAccessedAt) : new Date()
       }));
       
-      const loadedPrefs = parsed.preferences || {};
-      this.preferences = {
-        ...this.preferences,
-        ...loadedPrefs,
-        userSkills: Array.isArray(loadedPrefs.userSkills) ? loadedPrefs.userSkills : [],
-        learnedStyles: Array.isArray(loadedPrefs.learnedStyles) ? loadedPrefs.learnedStyles : [],
+      const loadedPrefs = parsed.preferences || {};
+      this.preferences = {
+        ...this.preferences,
+        ...loadedPrefs,
+        userSkills: Array.isArray(loadedPrefs.userSkills) ? loadedPrefs.userSkills : [],
+        learnedStyles: Array.isArray(loadedPrefs.learnedStyles) ? loadedPrefs.learnedStyles : [],
         favorites: Array.isArray(loadedPrefs.favorites) ? loadedPrefs.favorites : [],
         topicsOfInterest: (loadedPrefs.topicsOfInterest || []).map(t => ({
           ...t,
@@ -101,11 +114,36 @@ export class AgentMemory {
     }
   }
 
-  async save() {
-    if (!this.persistenceEnabled) return false;
+  scheduleSave() {
+    if (!this.persistenceEnabled) return Promise.resolve(false);
+    if (this._saveTimer) {
+      clearTimeout(this._saveTimer);
+      this._saveTimer = null;
+      const superseded = this._saveTimerResolve;
+      this._saveTimerResolve = null;
+      if (superseded) superseded(false);
+    }
+    return new Promise(resolve => {
+      this._saveTimerResolve = resolve;
+      this._saveTimer = setTimeout(() => {
+        this._saveTimer = null;
+        const settle = this._saveTimerResolve;
+        this._saveTimerResolve = null;
+        this._flushSave().then(() => settle(true), () => settle(false));
+      }, SAVE_DEBOUNCE_MS);
+    });
+  }
+
+  _flushSave() {
+    const next = this._saveChain.then(() => this._writeMemoryFile());
+    this._saveChain = next.then(() => true, () => true);
+    return next;
+  }
+
+  async _writeMemoryFile() {
     try {
       if (!await this.init()) return false;
-      
+
       const serializablePrefs = {
         ...this.preferences,
         topicsOfInterest: (this.preferences.topicsOfInterest || []).map(t => ({
@@ -125,7 +163,7 @@ export class AgentMemory {
         stats: this.stats,
         lastSavedAt: new Date().toISOString()
       };
-      await fs.writeFile(this.storageFile, JSON.stringify(data, null, 2), { encoding: 'utf-8', mode: 0o600 });
+      await fs.writeFile(this.storageFile, JSON.stringify(data), { encoding: 'utf-8', mode: 0o600 });
       return true;
     } catch (error) {
       this._warnStorage(error);
@@ -133,6 +171,18 @@ export class AgentMemory {
     }
   }
 
+  async save() {
+    if (!this.persistenceEnabled) return false;
+    if (this._saveTimer) {
+      clearTimeout(this._saveTimer);
+      this._saveTimer = null;
+      const superseded = this._saveTimerResolve;
+      this._saveTimerResolve = null;
+      if (superseded) superseded(false);
+    }
+    return this._flushSave();
+  }
+
   addFact(fact, meta = {}) {
     const entry = {
       id: `fact_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
@@ -146,12 +196,37 @@ export class AgentMemory {
       tags: meta.tags || []
     };
     this.facts.push(entry);
+    if (this.facts.length > MAX_FACTS) {
+      let oldestIndex = 0;
+      let oldestTime = new Date(this.facts[0].lastAccessedAt || this.facts[0].createdAt || 0).getTime();
+      for (let i = 1; i < this.facts.length; i += 1) {
+        const time = new Date(this.facts[i].lastAccessedAt || this.facts[i].createdAt || 0).getTime();
+        if (time < oldestTime) {
+          oldestTime = time;
+          oldestIndex = i;
+        }
+      }
+      this.facts.splice(oldestIndex, 1);
+    }
     this.stats.totalFacts = this.facts.length;
-    this.save().catch(() => {});
+    this.scheduleSave().catch(() => {});
     return entry;
   }
 
-  scoreFactRelevance(fact, queryTerms = [], now = Date.now()) {
+  _compileTermMatchers(terms = []) {
+    const matchers = [];
+    for (const term of terms) {
+      if (!term || term.length < 2) continue;
+      matchers.push({
+        term,
+        lenBonus: Math.min(2.0, term.length / 4),
+        wordRegex: new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i')
+      });
+    }
+    return matchers;
+  }
+
+  scoreFactRelevance(fact, queryTerms = [], now = Date.now(), termMatchers = null) {
     if (!fact) return 0;
     const content = (fact.content || '').toLowerCase();
     const tags = (fact.tags || []).map(t => String(t).toLowerCase());
@@ -159,9 +234,10 @@ export class AgentMemory {
 
     let matchScore = 0;
     if (queryTerms.length > 0) {
-      for (const term of queryTerms) {
-        if (!term || term.length < 2) continue;
-        const termLenBonus = Math.min(2.0, term.length / 4);
+      const matchers = termMatchers || this._compileTermMatchers(queryTerms);
+      for (const matcher of matchers) {
+        const term = matcher.term;
+        const termLenBonus = matcher.lenBonus;
 
         if (tags.includes(term)) {
           matchScore += 5.0 * termLenBonus;
@@ -173,8 +249,7 @@ export class AgentMemory {
           matchScore += 2.5;
         }
 
-        const wordRegex = new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i');
-        if (wordRegex.test(content)) {
+        if (matcher.wordRegex.test(content)) {
           matchScore += 3.5 * termLenBonus;
         } else if (content.includes(term)) {
           matchScore += 1.8 * termLenBonus;
@@ -199,10 +274,11 @@ export class AgentMemory {
     const q = String(query || '').toLowerCase().trim();
     const terms = q ? q.split(/\s+/).filter(t => t.length >= 2) : [];
     const now = Date.now();
+    const matchers = this._compileTermMatchers(terms);
 
     const scored = this.facts.map(fact => ({
       fact,
-      score: this.scoreFactRelevance(fact, terms, now)
+      score: this.scoreFactRelevance(fact, terms, now, matchers)
     }));
 
     scored.sort((a, b) => b.score - a.score);
@@ -234,12 +310,14 @@ export class AgentMemory {
 
     const terms = q ? q.split(/\s+/).filter(t => t.length >= 2) : [];
     const now = Date.now();
+    const matchers = this._compileTermMatchers(terms);
 
-    results.sort((a, b) => {
-      const scoreA = this.scoreFactRelevance(a, terms, now);
-      const scoreB = this.scoreFactRelevance(b, terms, now);
-      return scoreB - scoreA;
-    });
+    const decorated = results.map(fact => ({
+      fact,
+      score: this.scoreFactRelevance(fact, terms, now, matchers)
+    }));
+    decorated.sort((a, b) => b.score - a.score);
+    results = decorated.map(entry => entry.fact);
 
     for (const fact of results.slice(0, limit)) {
       fact.lastAccessedAt = new Date();
@@ -254,13 +332,13 @@ export class AgentMemory {
     if (idx === -1) return false;
     this.facts.splice(idx, 1);
     this.stats.totalFacts = this.facts.length;
-    this.save().catch(() => {});
+    this.scheduleSave().catch(() => {});
     return true;
   }
 
   setPreference(key, value) {
     this.preferences[key] = value;
-    this.save().catch(() => {});
+    this.scheduleSave().catch(() => {});
   }
 
   addFavorite(entity = {}) {
@@ -285,7 +363,7 @@ export class AgentMemory {
     };
     this.preferences.favorites.unshift(favorite);
     this.preferences.favorites = this.preferences.favorites.slice(0, 200);
-    this.save().catch(() => {});
+    this.scheduleSave().catch(() => {});
     return { favorite, created: true };
   }
 
@@ -301,7 +379,7 @@ export class AgentMemory {
     const before = favorites.length;
     this.preferences.favorites = favorites.filter(item => item.id !== id);
     if (this.preferences.favorites.length === before) return false;
-    this.save().catch(() => {});
+    this.scheduleSave().catch(() => {});
     return true;
   }
 
@@ -330,275 +408,338 @@ export class AgentMemory {
     await fs.writeFile(filePath, content, 'utf-8');
     return { filePath, filename, count: favorites.length, size: (await fs.stat(filePath)).size };
   }
-
-  addUserSkill(instruction) {
-    const value = String(instruction || '').replace(/\s+/g, ' ').trim();
-    if (!value) return null;
-    if (value.length > 500) throw new Error('Skill instruction must be 500 characters or fewer.');
-    const duplicate = this.preferences.userSkills.find(skill => skill.instruction.toLowerCase() === value.toLowerCase());
-    if (duplicate) return duplicate;
-    const skill = { id: `skill_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`, instruction: value };
-    this.preferences.userSkills.push(skill);
-    this.preferences.userSkills = this.preferences.userSkills.slice(-20);
-    this.save().catch(() => {});
-    return skill;
-  }
-
-  removeUserSkill(id) {
-    const before = this.preferences.userSkills.length;
-    this.preferences.userSkills = this.preferences.userSkills.filter(skill => skill.id !== id);
-    if (this.preferences.userSkills.length === before) return false;
-    this.save().catch(() => {});
-    return true;
-  }
-
-  clearUserSkills() {
-    this.preferences.userSkills = [];
-    this.save().catch(() => {});
-  }
-
-  buildUserSkillContext() {
-    if (!this.preferences.skillsEnabled || this.preferences.userSkills.length === 0) return '';
-    return this.preferences.userSkills.map((skill, index) => `${index + 1}. ${skill.instruction}`).join('\n');
-  }
-
-  applyFeedbackDirectives(directives = []) {
-    const clean = (Array.isArray(directives) ? directives : [])
-      .filter(d => d && typeof d.text === 'string' && d.text.trim())
-      .slice(0, 6)
-      .map(d => ({
-        id: String(d.id || '').slice(0, 60),
-        kind: d.kind === 'avoid' ? 'avoid' : 'prefer',
-        text: String(d.text).replace(/\s+/g, ' ').trim().slice(0, 200),
-        support: Number.isFinite(Number(d.support)) ? Number(d.support) : 0,
-        updatedAt: d.updatedAt || new Date().toISOString(),
-      }));
-    this.preferences.learnedStyles = clean;
-    this.save().catch(() => {});
-    return clean;
-  }
-
-  buildFeedbackStyleContext() {
-    const styles = Array.isArray(this.preferences.learnedStyles) ? this.preferences.learnedStyles : [];
-    if (styles.length === 0) return '';
-    return styles.map(s => `- ${s.text}`).join('\n');
-  }
-
-  
-  async savePreferences() {
-    await this.save();
-  }
-
-  
-  trackTopicInterest(topic) {
-    const existing = this.preferences.topicsOfInterest.find(
-      t => t.topic.toLowerCase() === topic.toLowerCase()
-    );
-    if (existing) {
-      existing.count++;
-      existing.lastSeen = new Date();
-    } else {
-      this.preferences.topicsOfInterest.push({
-        topic,
-        count: 1,
-        lastSeen: new Date()
-      });
-    }
-   
-    this.preferences.topicsOfInterest.sort((a, b) => b.count - a.count);
-    this.preferences.topicsOfInterest = this.preferences.topicsOfInterest.slice(0, 20);
-    this.save().catch(() => {});
-  }
-
-
-  getTopTopics(limit = 5) {
-    return this.preferences.topicsOfInterest.slice(0, limit);
-  }
-
-  
+
+  addUserSkill(instruction) {
+    const value = String(instruction || '').replace(/\s+/g, ' ').trim();
+    if (!value) return null;
+    if (value.length > 500) throw new Error('Skill instruction must be 500 characters or fewer.');
+    const duplicate = this.preferences.userSkills.find(skill => skill.instruction.toLowerCase() === value.toLowerCase());
+    if (duplicate) return duplicate;
+    const skill = { id: `skill_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`, instruction: value };
+    this.preferences.userSkills.push(skill);
+    this.preferences.userSkills = this.preferences.userSkills.slice(-20);
+    this.scheduleSave().catch(() => {});
+    return skill;
+  }
+
+  removeUserSkill(id) {
+    const before = this.preferences.userSkills.length;
+    this.preferences.userSkills = this.preferences.userSkills.filter(skill => skill.id !== id);
+    if (this.preferences.userSkills.length === before) return false;
+    this.scheduleSave().catch(() => {});
+    return true;
+  }
+
+  clearUserSkills() {
+    this.preferences.userSkills = [];
+    this.scheduleSave().catch(() => {});
+  }
+
+  buildUserSkillContext() {
+    if (!this.preferences.skillsEnabled || this.preferences.userSkills.length === 0) return '';
+    return this.preferences.userSkills.map((skill, index) => `${index + 1}. ${skill.instruction}`).join('\n');
+  }
+
+  applyFeedbackDirectives(directives = []) {
+    const clean = (Array.isArray(directives) ? directives : [])
+      .filter(d => d && typeof d.text === 'string' && d.text.trim())
+      .slice(0, 6)
+      .map(d => ({
+        id: String(d.id || '').slice(0, 60),
+        kind: d.kind === 'avoid' ? 'avoid' : 'prefer',
+        text: String(d.text).replace(/\s+/g, ' ').trim().slice(0, 200),
+        support: Number.isFinite(Number(d.support)) ? Number(d.support) : 0,
+        updatedAt: d.updatedAt || new Date().toISOString(),
+      }));
+    this.preferences.learnedStyles = clean;
+    this.scheduleSave().catch(() => {});
+    return clean;
+  }
+
+  buildFeedbackStyleContext() {
+    const styles = Array.isArray(this.preferences.learnedStyles) ? this.preferences.learnedStyles : [];
+    if (styles.length === 0) return '';
+    return styles.map(s => `- ${s.text}`).join('\n');
+  }
+
+  
+  async savePreferences() {
+    await this.save();
+  }
+
+  
+  trackTopicInterest(topic) {
+    const existing = this.preferences.topicsOfInterest.find(
+      t => t.topic.toLowerCase() === topic.toLowerCase()
+    );
+    if (existing) {
+      existing.count++;
+      existing.lastSeen = new Date();
+    } else {
+      this.preferences.topicsOfInterest.push({
+        topic,
+        count: 1,
+        lastSeen: new Date()
+      });
+    }
+   
+    this.preferences.topicsOfInterest.sort((a, b) => b.count - a.count);
+    this.preferences.topicsOfInterest = this.preferences.topicsOfInterest.slice(0, 20);
+    this.scheduleSave().catch(() => {});
+  }
+
+
+  getTopTopics(limit = 5) {
+    return this.preferences.topicsOfInterest.slice(0, limit);
+  }
+
+  
   async archiveSession(sessionData) {
     if (!this.persistenceEnabled) return null;
-    const archive = {
-      id: sessionData.id,
-      createdAt: sessionData.createdAt,
-      endedAt: new Date(),
-      messageCount: sessionData.messages?.length || 0,
-      stats: { ...sessionData.stats },
-      thinkingMode: sessionData.thinkingMode,
-      summary: null 
-    };
-
-   
-    let archivedToDisk = false;
-    try {
-      if (!await this.init()) return null;
+    const archive = {
+      id: sessionData.id,
+      createdAt: sessionData.createdAt,
+      endedAt: new Date(),
+      messageCount: sessionData.messages?.length || 0,
+      stats: { ...sessionData.stats },
+      thinkingMode: sessionData.thinkingMode,
+      summary: null 
+    };
+
+   
+    let archivedToDisk = false;
+    try {
+      if (!await this.init()) return null;
       const safeId = String(sessionData.id || '').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 100);
       if (!safeId) return null;
       const sessionFile = path.join(SESSIONS_DIR, `${safeId}.json`);
       await fs.writeFile(sessionFile, JSON.stringify(redactSensitiveValue(sessionData), null, 2), { encoding: 'utf-8', mode: 0o600 });
-      archivedToDisk = true;
-    } catch (err) {
-      this._warnStorage(err);
-    }
-
-    if (!archivedToDisk) return null;
-
-    this.sessions.push(archive);
-    this.stats.totalSessions = this.sessions.length;
-    await this.save();
-    return archive;
-  }
-
-  getArchivedSessions(limit = 20) {
-    return this.sessions
-      .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
-      .slice(0, limit);
-  }
-
+      archivedToDisk = true;
+    } catch (err) {
+      this._warnStorage(err);
+    }
+
+    if (!archivedToDisk) return null;
+
+    this.sessions.push(archive);
+    this.stats.totalSessions = this.sessions.length;
+    await this.save();
+    return archive;
+  }
+
+  getArchivedSessions(limit = 20) {
+    return [...this.sessions]
+      .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+      .slice(0, limit);
+  }
+
   async loadArchivedSession(sessionId) {
     if (!this.persistenceEnabled) return null;
     try {
       const safeId = String(sessionId || '').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 100);
       if (!safeId) return null;
       const sessionFile = path.join(SESSIONS_DIR, `${safeId}.json`);
-      const data = await fs.readFile(sessionFile, 'utf-8');
-      return JSON.parse(data);
-    } catch {
-      return null;
-    }
-  }
-
-
-  async consolidateSession(sessionData) {
-    if (!sessionData?.messages?.length) return null;
-
-    const userMessages = sessionData.messages
-      .filter(m => m.role === 'user')
-      .map(m => {
-        const textPart = m.parts?.find(p => p.type === 'text');
-        return textPart?.content || '';
-      })
-      .filter(Boolean);
-
-    const assistantMessages = sessionData.messages
-      .filter(m => m.role === 'assistant')
-      .map(m => {
-        const textPart = m.parts?.find(p => p.type === 'text');
-        return textPart?.content || '';
-      })
-      .filter(Boolean);
-
-    const topics = this._extractTopics(userMessages);
-
-    for (const topic of topics) {
-      this.trackTopicInterest(topic);
-    }
-
-    const summary = {
-      id: `sum_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
-      sessionId: sessionData.id,
-      createdAt: new Date(),
-      topics,
-      questionCount: userMessages.length,
-      keyExchanges: userMessages.slice(0, 5).map((q, i) => ({
-        question: q.slice(0, 200),
-        answerPreview: (assistantMessages[i] || '').slice(0, 200)
-      })),
-      durationMs: sessionData.stats?.totalDurationMs || 0,
-      toolCalls: sessionData.stats?.totalToolCalls || 0
-    };
-
-    this.summaries.push(summary);
-    this.stats.totalConsolidations = this.summaries.length;
-    this.stats.lastConsolidationAt = new Date();
-    
-    const archived = this.sessions.find(s => s.id === sessionData.id);
-    if (archived) {
-      archived.summary = summary;
-    }
-
-    await this.save();
-    return summary;
-  }
-
-  _extractTopics(messages) {
-    const topicKeywords = {
-      'drama': ['drama', 'series', 'ละคร', '剧', '电视', 'tv series', 'film', 'movie', 'work'],
-      'music': ['song', 'music', 'mv', 'single', 'ost', 'เพลง', '歌', 'album', 'discography'],
-      'brand': ['brand', 'ambassador', 'endorsement', 'แบรนด์', '品牌', 'commercial'],
-      'awards': ['award', 'honor', 'ceremony', 'รางวัล', '奖', 'winner'],
-      'profile': ['profile', 'bio', 'birthday', 'age', 'ประวัติ', '资料', '个人信息'],
-      'timeline': ['career', 'timeline', 'history', 'era', 'เส้นทาง', '经历', 'ปี'],
-      'news': ['news', 'latest', 'recent', 'update', 'ข่าว', '最新', 'ล่าสุด'],
-      'video': ['video', 'stage', 'performance', 'live', 'คลิป', '视频', '舞台'],
-      'social': ['weibo', 'douyin', 'instagram', 'social media', 'โซเชียล', '微博'],
-      'gallery': ['photo', 'picture', 'gallery', 'fashion', 'photoshoot', 'ภาพ', '照片']
-    };
-
-    const topicCounts = {};
-    const allText = messages.join(' ').toLowerCase();
-
-    for (const [topic, keywords] of Object.entries(topicKeywords)) {
-      const count = keywords.reduce((acc, kw) => {
-        const regex = new RegExp(`\\b${kw}\\b`, 'gi');
-        return acc + (allText.match(regex) || []).length;
-      }, 0);
-      if (count > 0) topicCounts[topic] = count;
-    }
-
-    return Object.entries(topicCounts)
-      .sort(([, a], [, b]) => b - a)
-      .slice(0, 5)
-      .map(([topic]) => topic);
-  }
-
-
+      const data = await fs.readFile(sessionFile, 'utf-8');
+      return JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+
+
+  async consolidateSession(sessionData) {
+    if (!sessionData?.messages?.length) return null;
+
+    const userMessages = sessionData.messages
+      .filter(m => m.role === 'user')
+      .map(m => {
+        const textPart = m.parts?.find(p => p.type === 'text');
+        return textPart?.content || '';
+      })
+      .filter(Boolean);
+
+    const assistantMessages = sessionData.messages
+      .filter(m => m.role === 'assistant')
+      .map(m => {
+        const textPart = m.parts?.find(p => p.type === 'text');
+        return textPart?.content || '';
+      })
+      .filter(Boolean);
+
+    const topics = this._extractTopics(userMessages);
+
+    for (const topic of topics) {
+      this.trackTopicInterest(topic);
+    }
+
+    const summary = {
+      id: `sum_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+      sessionId: sessionData.id,
+      createdAt: new Date(),
+      topics,
+      questionCount: userMessages.length,
+      keyExchanges: userMessages.slice(0, 5).map((q, i) => ({
+        question: q.slice(0, 200),
+        answerPreview: (assistantMessages[i] || '').slice(0, 200)
+      })),
+      durationMs: sessionData.stats?.totalDurationMs || 0,
+      toolCalls: sessionData.stats?.totalToolCalls || 0
+    };
+
+    this.summaries.push(summary);
+    this.stats.totalConsolidations = this.summaries.length;
+    this.stats.lastConsolidationAt = new Date();
+    
+    const archived = this.sessions.find(s => s.id === sessionData.id);
+    if (archived) {
+      archived.summary = summary;
+    }
+
+    await this.save();
+    return summary;
+  }
+
+  _extractTopics(messages) {
+    const topicKeywords = {
+      'drama': ['drama', 'series', 'ละคร', '剧', '电视', 'tv series', 'film', 'movie', 'work'],
+      'music': ['song', 'music', 'mv', 'single', 'ost', 'เพลง', '歌', 'album', 'discography'],
+      'brand': ['brand', 'ambassador', 'endorsement', 'แบรนด์', '品牌', 'commercial'],
+      'awards': ['award', 'honor', 'ceremony', 'รางวัล', '奖', 'winner'],
+      'profile': ['profile', 'bio', 'birthday', 'age', 'ประวัติ', '资料', '个人信息'],
+      'timeline': ['career', 'timeline', 'history', 'era', 'เส้นทาง', '经历', 'ปี'],
+      'news': ['news', 'latest', 'recent', 'update', 'ข่าว', '最新', 'ล่าสุด'],
+      'video': ['video', 'stage', 'performance', 'live', 'คลิป', '视频', '舞台'],
+      'social': ['weibo', 'douyin', 'instagram', 'social media', 'โซเชียล', '微博'],
+      'gallery': ['photo', 'picture', 'gallery', 'fashion', 'photoshoot', 'ภาพ', '照片']
+    };
+
+    const topicCounts = {};
+    const allText = messages.join(' ').toLowerCase();
+
+    for (const [topic, keywords] of Object.entries(topicKeywords)) {
+      const count = keywords.reduce((acc, kw) => {
+        const regex = new RegExp(`\\b${kw}\\b`, 'gi');
+        return acc + (allText.match(regex) || []).length;
+      }, 0);
+      if (count > 0) topicCounts[topic] = count;
+    }
+
+    return Object.entries(topicCounts)
+      .sort(([, a], [, b]) => b - a)
+      .slice(0, 5)
+      .map(([topic]) => topic);
+  }
+
+
   buildMemoryContext(currentQuery = '') {
-    const parts = [];
-
-    if (this.preferences.language) {
-      parts.push(`User's preferred language: ${this.preferences.language}`);
-    }
-
-    const userSkillContext = this.buildUserSkillContext();
-    if (userSkillContext) {
-      parts.push(`User-taught response skills (follow these preferences unless they conflict with safety or verified facts):\n${userSkillContext}`);
-    }
-
-    const feedbackStyleContext = this.buildFeedbackStyleContext();
-    if (feedbackStyleContext) {
-      parts.push(`Learned answer-style preferences (distilled from this user's like/dislike feedback — answer this way unless it conflicts with safety or verified facts):\n${feedbackStyleContext}`);
-    }
-
-    const topTopics = this.getTopTopics(5);
-    if (topTopics.length > 0) {
-      const topicList = topTopics.map(t => `${t.topic} (${t.count}x)`).join(', ');
-      parts.push(`User frequently asks about: ${topicList}`);
-    }
-
-    const relevantFacts = currentQuery ? this.getRelevantFacts(currentQuery, 8) : this.facts.slice(-8);
-    if (relevantFacts.length > 0) {
-      const factList = relevantFacts.map(f => `- ${f.content}`).join('\n');
-      parts.push(`Known facts from previous conversations:\n${factList}`);
-    }
-
-    const recentSummaries = this.summaries
-      .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
-      .slice(0, 3);
-    if (recentSummaries.length > 0) {
-      const sumList = recentSummaries.map(s => {
-        const date = new Date(s.createdAt).toLocaleDateString();
-        const topics = s.topics.join(', ');
-        return `- [${date}] Topics: ${topics} (${s.questionCount} questions)`;
-      }).join('\n');
-      parts.push(`Recent conversation themes:\n${sumList}`);
-    }
-
-    if (parts.length === 0) return '';
-
+    const parts = [];
+
+    if (this.preferences.language) {
+      parts.push(`User's preferred language: ${this.preferences.language}`);
+    }
+
+    const userSkillContext = this.buildUserSkillContext();
+    if (userSkillContext) {
+      parts.push(`User-taught response skills (follow these preferences unless they conflict with safety or verified facts):\n${userSkillContext}`);
+    }
+
+    const feedbackStyleContext = this.buildFeedbackStyleContext();
+    if (feedbackStyleContext) {
+      parts.push(`Learned answer-style preferences (distilled from this user's like/dislike feedback — answer this way unless it conflicts with safety or verified facts):\n${feedbackStyleContext}`);
+    }
+
+    const topTopics = this.getTopTopics(5);
+    if (topTopics.length > 0) {
+      const topicList = topTopics.map(t => `${t.topic} (${t.count}x)`).join(', ');
+      parts.push(`User frequently asks about: ${topicList}`);
+    }
+
+    const relevantFacts = currentQuery ? this.getRelevantFacts(currentQuery, 8) : this.facts.slice(-8);
+    if (relevantFacts.length > 0) {
+      const factList = relevantFacts.map(f => `- ${f.content}`).join('\n');
+      parts.push(`Known facts from previous conversations:\n${factList}`);
+    }
+
+    const recentSummaries = [...this.summaries]
+      .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+      .slice(0, 3);
+    if (recentSummaries.length > 0) {
+      const sumList = recentSummaries.map(s => {
+        const date = new Date(s.createdAt).toLocaleDateString();
+        const topics = s.topics.join(', ');
+        return `- [${date}] Topics: ${topics} (${s.questionCount} questions)`;
+      }).join('\n');
+      parts.push(`Recent conversation themes:\n${sumList}`);
+    }
+
+    if (parts.length === 0) return '';
+
     return `\n\n=== LONG-TERM MEMORY CONTEXT ===\n${parts.join('\n\n')}\n=== END MEMORY CONTEXT ===`;
   }
 
+  setActiveRunId(runId) {
+    this.activeRunId = runId;
+  }
+
+  getActiveRunId() {
+    return this.activeRunId;
+  }
+
+  async checkpointStep({ runId, stepName, status, summary, metadata } = {}) {
+    const targetRunId = runId || this.activeRunId;
+    return this.hierarchicalStore.checkpointStep({ runId: targetRunId, stepName, status, summary, metadata });
+  }
+
+  async recordFailure({ runId, errorTrace, recoveryAction, toolName } = {}) {
+    const targetRunId = runId || this.activeRunId;
+    return this.hierarchicalStore.recordFailure({ runId: targetRunId, errorTrace, recoveryAction, toolName });
+  }
+
+  async loadActiveRun(runId) {
+    const targetRunId = runId || this.activeRunId;
+    return this.hierarchicalStore.loadActiveRun(targetRunId);
+  }
+
+  async setGuideline(domain, text, type = 'user') {
+    return this.hierarchicalStore.setNode(`kiku/guidelines/${domain}`, text, { type });
+  }
+
+  async getGuideline(domain) {
+    const node = await this.hierarchicalStore.getNode(`kiku/guidelines/${domain}`);
+    return node?.content || null;
+  }
+
+  async addReflection(toolOrDomain, data) {
+    return this.hierarchicalStore.setNode(`kiku/reflections/${toolOrDomain}`, data, { type: 'context' });
+  }
+
+  async getReflections(toolOrDomain = '') {
+    if (toolOrDomain) {
+      const node = await this.hierarchicalStore.getNode(`kiku/reflections/${toolOrDomain}`);
+      return node?.content || null;
+    }
+    const nodes = await this.hierarchicalStore.listNodes('kiku/reflections/');
+    return nodes.map(n => n.content);
+  }
+
+  async triggerPostRunCompaction(runId, finalStatus = 'COMPLETED', metadata = {}) {
+    const targetRunId = runId || this.activeRunId;
+    return this.reflectionWorker.processPostRunCompaction(targetRunId, finalStatus, metadata);
+  }
+
+  async purgeExpiredArchives() {
+    return this.hierarchicalStore.purgeExpiredArchives();
+  }
+
+  async addMemoryContext(options = {}) {
+    return this.contextAllocator.allocateContext({
+      memory: this,
+      currentQuery: options.currentQuery || '',
+      activeRunId: options.activeRunId || this.activeRunId,
+      maxTokens: options.maxTokens
+    });
+  }
+
   getFactsByCategory() {
     return this.facts.reduce((counts, fact) => {
       const category = String(fact?.category || 'general');
@@ -608,160 +749,160 @@ export class AgentMemory {
   }
 
   getStatus() {
-    return {
-      factsCount: this.facts.length,
-      factsByCategory: this.getFactsByCategory(),
-      preferences: this.preferences,
-      sessionsCount: this.sessions.length,
-      summariesCount: this.summaries.length,
-      topTopics: this.getTopTopics(10),
-      stats: this.stats,
-      lastConsolidationAt: this.stats.lastConsolidationAt,
-      memoryFileSize: null
-    };
-  }
-
-  async importFromJSON(filePath) {
-    try {
-      const raw = await fs.readFile(filePath, 'utf-8');
-      const data = JSON.parse(raw);
-
-      if (!data.facts && !data.preferences && !data.sessions) {
-        return { success: false, message: 'Invalid memory file format — missing facts, preferences, or sessions.' };
-      }
-
-      let factsImported = 0;
-      let factsSkipped = 0;
-      let topicsImported = 0;
-
-      if (Array.isArray(data.facts)) {
-        for (const fact of data.facts) {
-          const isDuplicate = this.facts.some(
-            existing => existing.content === fact.content
-          );
-          if (!isDuplicate && fact.content) {
-            this.facts.push({
-              id: fact.id || `fact_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
-              content: fact.content,
-              category: fact.category || 'imported',
-              source: fact.source || 'import',
-              confidence: fact.confidence || 'high',
-              createdAt: fact.createdAt ? new Date(fact.createdAt) : new Date(),
-              lastAccessedAt: new Date(),
-              accessCount: 0,
-              tags: fact.tags || []
-            });
-            factsImported++;
-          } else {
-            factsSkipped++;
-          }
-        }
-      }
-
-      if (data.preferences) {
-        if (data.preferences.language) {
-          this.preferences.language = data.preferences.language;
-        }
-        if (data.preferences.responseStyle) {
-          this.preferences.responseStyle = data.preferences.responseStyle;
-        }
-        if (Array.isArray(data.preferences.topicsOfInterest)) {
-          for (const topic of data.preferences.topicsOfInterest) {
-            const existing = this.preferences.topicsOfInterest.find(
-              t => t.topic.toLowerCase() === topic.topic.toLowerCase()
-            );
-            if (existing) {
-              existing.count += topic.count || 1;
-              existing.lastSeen = new Date();
-            } else {
-              this.preferences.topicsOfInterest.push({
-                topic: topic.topic,
-                count: topic.count || 1,
-                lastSeen: topic.lastSeen ? new Date(topic.lastSeen) : new Date()
-              });
-              topicsImported++;
-            }
-          }
-          this.preferences.topicsOfInterest.sort((a, b) => b.count - a.count);
-          this.preferences.topicsOfInterest = this.preferences.topicsOfInterest.slice(0, 20);
-        }
-      }
-
-      if (Array.isArray(data.sessions)) {
-        for (const session of data.sessions) {
-          const isDuplicate = this.sessions.some(s => s.id === session.id);
-          if (!isDuplicate) {
-            this.sessions.push(session);
-          }
-        }
-      }
-
-      if (Array.isArray(data.summaries)) {
-        for (const summary of data.summaries) {
-          const isDuplicate = this.summaries.some(s => s.id === summary.id);
-          if (!isDuplicate) {
-            this.summaries.push(summary);
-          }
-        }
-      }
-
-      this.stats.totalFacts = this.facts.length;
-      this.stats.totalSessions = this.sessions.length;
-      this.stats.totalConsolidations = this.summaries.length;
-
-      await this.save();
-
-      return {
-        success: true,
-        factsImported,
-        factsSkipped,
-        topicsImported,
-        totalFacts: this.facts.length,
-        totalSessions: this.sessions.length,
-        totalSummaries: this.summaries.length
-      };
-    } catch (error) {
-      return { success: false, message: error.message };
-    }
-  }
-
-  async exportToJSON() {
-    const exportDir = EXPORT_DIR;
-    try {
-      await fs.mkdir(exportDir, { recursive: true });
-    } catch {}
-
-    const now = new Date();
-    const timestamp = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const filename = `kiku-memory-${timestamp}.json`;
-    const filePath = path.join(exportDir, filename);
-
-    const exportData = {
-      exportedAt: now.toISOString(),
-      stats: this.stats,
-      preferences: {
-        ...this.preferences,
-        topicsOfInterest: (this.preferences.topicsOfInterest || []).map(t => ({
-          ...t,
-          lastSeen: t.lastSeen ? t.lastSeen.toISOString() : null
-        }))
-      },
-      facts: this.facts.map(f => ({
-        ...f,
-        createdAt: f.createdAt ? f.createdAt.toISOString() : f.createdAt,
-        lastAccessedAt: f.lastAccessedAt ? f.lastAccessedAt.toISOString() : f.lastAccessedAt
-      })),
-      factsByCategory: this.getFactsByCategory(),
-      sessions: this.sessions,
-      summaries: this.summaries
-    };
-
-    await fs.writeFile(filePath, JSON.stringify(exportData, null, 2), 'utf-8');
-    return { filePath, filename, size: (await fs.stat(filePath)).size };
-  }
-
-  async clearAll() {
-    this.facts = [];
+    return {
+      factsCount: this.facts.length,
+      factsByCategory: this.getFactsByCategory(),
+      preferences: this.preferences,
+      sessionsCount: this.sessions.length,
+      summariesCount: this.summaries.length,
+      topTopics: this.getTopTopics(10),
+      stats: this.stats,
+      lastConsolidationAt: this.stats.lastConsolidationAt,
+      memoryFileSize: null
+    };
+  }
+
+  async importFromJSON(filePath) {
+    try {
+      const raw = await fs.readFile(filePath, 'utf-8');
+      const data = JSON.parse(raw);
+
+      if (!data.facts && !data.preferences && !data.sessions) {
+        return { success: false, message: 'Invalid memory file format — missing facts, preferences, or sessions.' };
+      }
+
+      let factsImported = 0;
+      let factsSkipped = 0;
+      let topicsImported = 0;
+
+      if (Array.isArray(data.facts)) {
+        for (const fact of data.facts) {
+          const isDuplicate = this.facts.some(
+            existing => existing.content === fact.content
+          );
+          if (!isDuplicate && fact.content) {
+            this.facts.push({
+              id: fact.id || `fact_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+              content: fact.content,
+              category: fact.category || 'imported',
+              source: fact.source || 'import',
+              confidence: fact.confidence || 'high',
+              createdAt: fact.createdAt ? new Date(fact.createdAt) : new Date(),
+              lastAccessedAt: new Date(),
+              accessCount: 0,
+              tags: fact.tags || []
+            });
+            factsImported++;
+          } else {
+            factsSkipped++;
+          }
+        }
+      }
+
+      if (data.preferences) {
+        if (data.preferences.language) {
+          this.preferences.language = data.preferences.language;
+        }
+        if (data.preferences.responseStyle) {
+          this.preferences.responseStyle = data.preferences.responseStyle;
+        }
+        if (Array.isArray(data.preferences.topicsOfInterest)) {
+          for (const topic of data.preferences.topicsOfInterest) {
+            const existing = this.preferences.topicsOfInterest.find(
+              t => t.topic.toLowerCase() === topic.topic.toLowerCase()
+            );
+            if (existing) {
+              existing.count += topic.count || 1;
+              existing.lastSeen = new Date();
+            } else {
+              this.preferences.topicsOfInterest.push({
+                topic: topic.topic,
+                count: topic.count || 1,
+                lastSeen: topic.lastSeen ? new Date(topic.lastSeen) : new Date()
+              });
+              topicsImported++;
+            }
+          }
+          this.preferences.topicsOfInterest.sort((a, b) => b.count - a.count);
+          this.preferences.topicsOfInterest = this.preferences.topicsOfInterest.slice(0, 20);
+        }
+      }
+
+      if (Array.isArray(data.sessions)) {
+        for (const session of data.sessions) {
+          const isDuplicate = this.sessions.some(s => s.id === session.id);
+          if (!isDuplicate) {
+            this.sessions.push(session);
+          }
+        }
+      }
+
+      if (Array.isArray(data.summaries)) {
+        for (const summary of data.summaries) {
+          const isDuplicate = this.summaries.some(s => s.id === summary.id);
+          if (!isDuplicate) {
+            this.summaries.push(summary);
+          }
+        }
+      }
+
+      this.stats.totalFacts = this.facts.length;
+      this.stats.totalSessions = this.sessions.length;
+      this.stats.totalConsolidations = this.summaries.length;
+
+      await this.save();
+
+      return {
+        success: true,
+        factsImported,
+        factsSkipped,
+        topicsImported,
+        totalFacts: this.facts.length,
+        totalSessions: this.sessions.length,
+        totalSummaries: this.summaries.length
+      };
+    } catch (error) {
+      return { success: false, message: error.message };
+    }
+  }
+
+  async exportToJSON() {
+    const exportDir = EXPORT_DIR;
+    try {
+      await fs.mkdir(exportDir, { recursive: true });
+    } catch {}
+
+    const now = new Date();
+    const timestamp = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const filename = `kiku-memory-${timestamp}.json`;
+    const filePath = path.join(exportDir, filename);
+
+    const exportData = {
+      exportedAt: now.toISOString(),
+      stats: this.stats,
+      preferences: {
+        ...this.preferences,
+        topicsOfInterest: (this.preferences.topicsOfInterest || []).map(t => ({
+          ...t,
+          lastSeen: t.lastSeen ? t.lastSeen.toISOString() : null
+        }))
+      },
+      facts: this.facts.map(f => ({
+        ...f,
+        createdAt: f.createdAt ? f.createdAt.toISOString() : f.createdAt,
+        lastAccessedAt: f.lastAccessedAt ? f.lastAccessedAt.toISOString() : f.lastAccessedAt
+      })),
+      factsByCategory: this.getFactsByCategory(),
+      sessions: this.sessions,
+      summaries: this.summaries
+    };
+
+    await fs.writeFile(filePath, JSON.stringify(exportData, null, 2), 'utf-8');
+    return { filePath, filename, size: (await fs.stat(filePath)).size };
+  }
+
+  async clearAll() {
+    this.facts = [];
     this.preferences = {
       language: null,
       topicsOfInterest: [],
@@ -769,34 +910,34 @@ export class AgentMemory {
       userSkills: [],
       skillsEnabled: true,
       favorites: [],
-    };
-    this.sessions = [];
-    this.summaries = [];
-    this.stats = {
-      totalFacts: 0,
-      totalSessions: 0,
-      totalConsolidations: 0,
-      lastConsolidationAt: null,
-      createdAt: new Date()
-    };
-    await this.save();
-    return true;
-  }
-
-  async getStorageSize() {
-    try {
+    };
+    this.sessions = [];
+    this.summaries = [];
+    this.stats = {
+      totalFacts: 0,
+      totalSessions: 0,
+      totalConsolidations: 0,
+      lastConsolidationAt: null,
+      createdAt: new Date()
+    };
+    await this.save();
+    return true;
+  }
+
+  async getStorageSize() {
+    try {
       const stat = await fs.stat(this.storageFile);
-      return stat.size;
-    } catch {
-      return 0;
-    }
-  }
-
-  static formatBytes(bytes) {
-    if (bytes === 0) return '0 B';
-    const k = 1024;
-    const sizes = ['B', 'KB', 'MB', 'GB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
-  }
-}
+      return stat.size;
+    } catch {
+      return 0;
+    }
+  }
+
+  static formatBytes(bytes) {
+    if (bytes === 0) return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+  }
+}