@darksol/terminal 0.8.1 → 0.9.0

package/README.md

@@ -15,7 +15,7 @@ A unified CLI for market intel, trading, AI-powered analysis, on-chain oracle, c
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-gold.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
 
-- Current release: **0.8.1**
+- Current release: **0.9.0**
 - Changelog: `CHANGELOG.md`
 
 ## Install
@@ -56,9 +56,16 @@ darksol bridge send --from base --to arbitrum --token ETH -a 0.1
 darksol bridge status 0xTxHash...
 darksol bridge chains
 
-# AI trading assistant
+# Set up your agent identity
+darksol soul
+
+# AI trading assistant (now with personality + memory)
 darksol ai chat
 
+# View/search persistent memories
+darksol memory show
+darksol memory search "preferred chain"
+
 # Agent email
 darksol mail setup
 darksol mail send --to user@example.com --subject "Hello"
@@ -114,6 +121,8 @@ ai <prompt>   # chat with trading assistant
 | `trade` | Swap via LI.FI (31 DEXs) + Uniswap V3 fallback, snipe | Gas only |
 | `bridge` | Cross-chain bridge via LI.FI (60 chains, 27 bridges) | Gas only |
 | `dca` | Dollar-cost averaging engine | Gas only |
+| `soul` | Agent identity & personality configuration | Free |
+| `memory` | Persistent cross-session memory store | Free |
 | `ai` | LLM-powered trading assistant & intent execution | Provider dependent |
 | `agent` | Secure agent signer (PK-isolated proxy) | Free |
 | `keys` | Encrypted API key vault (LLMs/data/RPCs) | Free |
@@ -190,9 +199,49 @@ darksol agent docs
 
 ---
 
+## 👤 Agent Soul System
+
+Give your terminal agent a name, personality, and persistent memory.
+
+```bash
+# First-run setup (or run anytime)
+darksol soul
+
+# View current identity
+darksol soul show
+
+# Reset and reconfigure
+darksol soul reset
+```
+
+**What it does:**
+- **Your name** — the agent addresses you personally
+- **Agent name** — name your AI (default: Darksol)
+- **Tone** — professional, casual, hacker, friendly, sarcastic, or custom freeform
+- Persists across sessions — your agent remembers who it is
+- Auto-injected into every LLM call as a system prompt
+
+**Session memory:** Conversations maintain context (up to 20 turns). When the limit is hit, older turns are summarized by the LLM — no hard context cliff.
+
+**Persistent memory:** Important facts, preferences, and decisions are auto-extracted and stored to disk (`~/.darksol/memory/`). Your agent learns over time.
+
+```bash
+# View recent memories
+darksol memory show --limit 20
+
+# Search memories
+darksol memory search "slippage preference"
+
+# Export / clear
+darksol memory export my-memories.json
+darksol memory clear
+```
+
+---
+
 ## 🧠 AI Trading Assistant
 
-Natural language trading powered by multi-provider LLM support.
+Natural language trading powered by multi-provider LLM support — now with soul personality and memory context.
 
 ```bash
 # Interactive chat with live market data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -26,8 +26,11 @@ import { addKey, removeKey, listKeys } from './config/keys.js';
 import { parseIntent, startChat, adviseStrategy, analyzeToken, executeIntent } from './llm/intent.js';
 import { startAgentSigner, showAgentDocs } from './wallet/agent-signer.js';
 import { listSkills, installSkill, skillInfo, uninstallSkill } from './services/skills.js';
-import { runSetupWizard, checkFirstRun } from './setup/wizard.js';
+import { runSetupWizard } from './setup/wizard.js';
+import { displaySoul, hasSoul, resetSoul, runSoulSetup } from './soul/index.js';
+import { clearMemories, exportMemories, getRecentMemories, searchMemories } from './memory/index.js';
 import { createRequire } from 'module';
+import { resolve } from 'path';
 const require = createRequire(import.meta.url);
 const { version: PKG_VERSION } = require('../package.json');
 
@@ -647,6 +650,101 @@ export function cli(argv) {
     .option('-m, --model <model>', 'Model name')
     .action((opts) => startChat(opts));
 
+  const soul = program
+    .command('soul')
+    .description('Identity and agent personality')
+    .action(async () => {
+      await runSoulSetup({ reset: !hasSoul() });
+    });
+
+  soul
+    .command('show')
+    .description('Show current soul configuration')
+    .action(() => displaySoul());
+
+  soul
+    .command('reset')
+    .description('Clear soul configuration and re-run setup')
+    .action(async () => {
+      resetSoul();
+      await runSoulSetup({ reset: true });
+    });
+
+  const memory = program
+    .command('memory')
+    .description('Persistent memory store');
+
+  memory
+    .command('show')
+    .description('Show recent persistent memories')
+    .option('-n, --limit <n>', 'Number of memories', '10')
+    .action(async (opts) => {
+      showMiniBanner();
+      showSection('MEMORY');
+      const memories = await getRecentMemories(parseInt(opts.limit, 10) || 10);
+      if (memories.length === 0) {
+        info('No persistent memories stored.');
+        console.log('');
+        return;
+      }
+
+      memories.forEach((memoryItem) => {
+        kvDisplay([
+          ['ID', memoryItem.id],
+          ['Category', memoryItem.category],
+          ['Source', memoryItem.source],
+          ['When', memoryItem.timestamp],
+          ['Content', memoryItem.content],
+        ]);
+        console.log('');
+      });
+    });
+
+  memory
+    .command('search <query...>')
+    .description('Search persistent memories')
+    .action(async (queryParts) => {
+      const query = queryParts.join(' ');
+      showMiniBanner();
+      showSection('MEMORY SEARCH');
+      info(`Query: ${query}`);
+      console.log('');
+
+      const matches = await searchMemories(query);
+      if (matches.length === 0) {
+        warn('No matching memories.');
+        console.log('');
+        return;
+      }
+
+      matches.slice(0, 10).forEach((memoryItem) => {
+        kvDisplay([
+          ['Category', memoryItem.category],
+          ['Source', memoryItem.source],
+          ['When', memoryItem.timestamp],
+          ['Content', memoryItem.content],
+        ]);
+        console.log('');
+      });
+    });
+
+  memory
+    .command('clear')
+    .description('Clear all persistent memories')
+    .action(async () => {
+      await clearMemories();
+      success('Persistent memory cleared.');
+    });
+
+  memory
+    .command('export [file]')
+    .description('Export persistent memories to JSON')
+    .action(async (file) => {
+      const target = resolve(file || `darksol-memory-export-${Date.now()}.json`);
+      await exportMemories(target);
+      success(`Memory exported to ${target}`);
+    });
+
   // ═══════════════════════════════════════
   // SETUP COMMAND
   // ═══════════════════════════════════════
@@ -951,6 +1049,9 @@ export function cli(argv) {
         ['Output', cfg.output],
         ['Slippage', `${cfg.slippage}%`],
         ['Gas Multiplier', `${cfg.gasMultiplier}x`],
+        ['Soul User', cfg.soul?.userName || theme.dim('(not set)')],
+        ['Agent Name', cfg.soul?.agentName || 'Darksol'],
+        ['Tone', cfg.soul?.tone || theme.dim('(not set)')],
         ['Mail', cfg.mailEmail || theme.dim('(not set)')],
         ['Version', PKG_VERSION],
         ['Config File', configPath()],
@@ -1205,6 +1306,8 @@ function showCommandList() {
     ['ai execute', 'Parse + execute a trade via AI'],
     ['agent start', 'Start secure agent signer'],
     ['keys', 'API key vault'],
+    ['soul', 'Identity and agent personality'],
+    ['memory', 'Persistent cross-session memory'],
     ['script', 'Execution scripts & strategies'],
     ['market', 'Market intel & token data'],
     ['oracle', 'On-chain random oracle'],

package/src/config/store.js

@@ -19,6 +19,15 @@ const config = new Conf({
     },
     slippage: { type: 'number', default: 0.5 },
     gasMultiplier: { type: 'number', default: 1.1 },
+    soul: {
+      type: 'object',
+      default: {
+        userName: '',
+        agentName: 'Darksol',
+        tone: '',
+        createdAt: '',
+      },
+    },
     dca: {
       type: 'object',
       default: {
@@ -48,6 +57,10 @@ export function setConfig(key, value) {
   config.set(key, value);
 }
 
+export function deleteConfig(key) {
+  config.delete(key);
+}
+
 export function getAllConfig() {
   return config.store;
 }

package/src/llm/engine.js

@@ -1,19 +1,14 @@
 import fetch from 'node-fetch';
-import { getKeyFromEnv, getKey, SERVICES } from '../config/keys.js';
+import { getKeyFromEnv, getKey } from '../config/keys.js';
 import { getConfig } from '../config/store.js';
-import { theme } from '../ui/theme.js';
-import { spinner, kvDisplay, success, error, warn, info } from '../ui/components.js';
-import { showSection } from '../ui/banner.js';
-
-// ──────────────────────────────────────────────────
-// LLM PROVIDER ADAPTERS
-// ──────────────────────────────────────────────────
+import { SessionMemory, extractMemories, searchMemories } from '../memory/index.js';
+import { formatSystemPrompt as formatSoulSystemPrompt } from '../soul/index.js';
 
 const PROVIDERS = {
   openai: {
     url: 'https://api.openai.com/v1/chat/completions',
     defaultModel: 'gpt-4o',
-    authHeader: (key) => ({ 'Authorization': `Bearer ${key}` }),
+    authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
     parseResponse: (data) => data.choices?.[0]?.message?.content,
     parseUsage: (data) => data.usage,
   },
@@ -25,9 +20,9 @@ const PROVIDERS = {
       model,
       max_tokens: 4096,
       system: systemPrompt,
-      messages: messages.map(m => ({
-        role: m.role === 'system' ? 'user' : m.role,
-        content: m.content,
+      messages: messages.map((message) => ({
+        role: message.role === 'system' ? 'user' : message.role,
+        content: message.content,
       })),
     }),
     parseResponse: (data) => data.content?.[0]?.text,
@@ -37,7 +32,7 @@ const PROVIDERS = {
     url: 'https://openrouter.ai/api/v1/chat/completions',
     defaultModel: 'anthropic/claude-sonnet-4-20250514',
     authHeader: (key) => ({
-      'Authorization': `Bearer ${key}`,
+      Authorization: `Bearer ${key}`,
       'HTTP-Referer': 'https://darksol.net',
       'X-Title': 'DARKSOL Terminal',
     }),
@@ -45,7 +40,7 @@ const PROVIDERS = {
     parseUsage: (data) => data.usage,
   },
   ollama: {
-    url: null, // Set from config
+    url: null,
     defaultModel: 'llama3.1',
     authHeader: () => ({}),
     parseResponse: (data) => data.choices?.[0]?.message?.content || data.message?.content,
@@ -60,32 +55,23 @@ const PROVIDERS = {
   },
 };
 
-// ──────────────────────────────────────────────────
-// LLM ENGINE
-// ──────────────────────────────────────────────────
-
 export class LLMEngine {
   constructor(opts = {}) {
     this.provider = opts.provider || getConfig('llm.provider') || 'openai';
     this.model = opts.model || getConfig('llm.model') || null;
     this.apiKey = opts.apiKey || null;
-    this.conversationHistory = [];
     this.systemPrompt = '';
-    this.maxHistoryTokens = opts.maxHistory || 8000;
     this.temperature = opts.temperature ?? 0.7;
+    this.sessionMemory = opts.sessionMemory || new SessionMemory({ maxTurns: opts.maxTurns || 20 });
+    this.maxRelevantMemories = opts.maxRelevantMemories || 5;
 
-    // Usage tracking
     this.totalInputTokens = 0;
     this.totalOutputTokens = 0;
     this.totalCalls = 0;
   }
 
-  /**
-   * Initialize the engine — resolve API key
-   */
   async init(vaultPassword) {
     if (!this.apiKey) {
-      // Try env first, then vault
       this.apiKey = getKeyFromEnv(this.provider);
       if (!this.apiKey && vaultPassword) {
         this.apiKey = await getKey(this.provider, vaultPassword);
@@ -93,7 +79,6 @@ export class LLMEngine {
     }
 
     if (!this.apiKey && this.provider !== 'ollama') {
-      // Try auto-stored keys as last resort
       const { getKeyAuto } = await import('../config/keys.js');
       this.apiKey = getKeyAuto(this.provider);
     }
@@ -111,47 +96,42 @@ export class LLMEngine {
       this.model = providerConfig.defaultModel;
     }
 
-    // Ollama URL from config
     if (this.provider === 'ollama') {
       const host = this.apiKey || getConfig('llm.ollamaHost') || 'http://localhost:11434';
       PROVIDERS.ollama.url = `${host}/v1/chat/completions`;
-      this.apiKey = 'ollama'; // placeholder
+      this.apiKey = 'ollama';
     }
 
     return this;
   }
 
-  /**
-   * Set the system prompt (persona/context for the LLM)
-   */
   setSystemPrompt(prompt) {
     this.systemPrompt = prompt;
     return this;
   }
 
-  /**
-   * Send a message and get a response
-   */
   async chat(userMessage, opts = {}) {
     const providerConfig = PROVIDERS[this.provider];
-
-    // Build messages array
+    const systemPrompt = opts.skipContext
+      ? (opts.systemPrompt || this.systemPrompt || '')
+      : await this._buildSystemPrompt(userMessage, opts.systemPrompt);
     const messages = [];
-    if (this.systemPrompt && this.provider !== 'anthropic') {
-      messages.push({ role: 'system', content: this.systemPrompt });
+
+    if (systemPrompt && this.provider !== 'anthropic') {
+      messages.push({ role: 'system', content: systemPrompt });
     }
 
-    // Add conversation history
-    for (const msg of this.conversationHistory) {
-      messages.push(msg);
+    if (!opts.skipContext) {
+      for (const message of this.sessionMemory.getContext()) {
+        messages.push(message);
+      }
     }
 
     messages.push({ role: 'user', content: userMessage });
 
-    // Build request body
     let body;
     if (providerConfig.buildBody) {
-      body = providerConfig.buildBody(this.model, messages, this.systemPrompt);
+      body = providerConfig.buildBody(this.model, messages, systemPrompt);
     } else {
       body = {
         model: this.model,
@@ -160,21 +140,17 @@ export class LLMEngine {
         max_tokens: opts.maxTokens || 4096,
       };
 
-      // JSON mode if requested
       if (opts.json) {
         body.response_format = { type: 'json_object' };
       }
     }
 
-    const url = providerConfig.url;
-    const headers = {
-      'Content-Type': 'application/json',
-      ...providerConfig.authHeader(this.apiKey),
-    };
-
-    const response = await fetch(url, {
+    const response = await fetch(providerConfig.url, {
       method: 'POST',
-      headers,
+      headers: {
+        'Content-Type': 'application/json',
+        ...providerConfig.authHeader(this.apiKey),
+      },
       body: JSON.stringify(body),
     });
 
@@ -187,18 +163,21 @@ export class LLMEngine {
     const content = providerConfig.parseResponse(data);
     const usage = providerConfig.parseUsage(data);
 
-    // Track usage
     this.totalCalls++;
     if (usage) {
       this.totalInputTokens += usage.input_tokens || usage.prompt_tokens || usage.input || 0;
       this.totalOutputTokens += usage.output_tokens || usage.completion_tokens || usage.output || 0;
     }
 
-    // Store in history
     if (!opts.ephemeral) {
-      this.conversationHistory.push({ role: 'user', content: userMessage });
-      this.conversationHistory.push({ role: 'assistant', content });
-      this._trimHistory();
+      this.sessionMemory.addTurn('user', userMessage);
+      this.sessionMemory.addTurn('assistant', content);
+      await this.sessionMemory.compact(this);
+
+      if (!opts.skipMemoryExtraction) {
+        await extractMemories(userMessage, 'user');
+        await extractMemories(content, 'assistant');
+      }
     }
 
     return {
@@ -209,24 +188,17 @@ export class LLMEngine {
     };
   }
 
-  /**
-   * One-shot completion (no history)
-   */
   async complete(prompt, opts = {}) {
     return this.chat(prompt, { ...opts, ephemeral: true });
   }
 
-  /**
-   * Get structured JSON response
-   */
   async json(prompt, opts = {}) {
     const result = await this.chat(
-      prompt + '\n\nRespond with valid JSON only. No markdown, no explanation.',
+      `${prompt}\n\nRespond with valid JSON only. No markdown, no explanation.`,
       { ...opts, ephemeral: true }
     );
 
     try {
-      // Extract JSON from response (handle markdown code blocks)
       let jsonStr = result.content;
       const match = jsonStr.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
       if (match) jsonStr = match[1];
@@ -239,17 +211,11 @@ export class LLMEngine {
     return result;
   }
 
-  /**
-   * Clear conversation history
-   */
   clearHistory() {
-    this.conversationHistory = [];
+    this.sessionMemory.clear();
     return this;
   }
 
-  /**
-   * Get usage stats
-   */
   getUsage() {
     return {
       calls: this.totalCalls,
@@ -261,36 +227,37 @@ export class LLMEngine {
     };
   }
 
-  /**
-   * Trim history to stay within token budget (rough estimate)
-   */
-  _trimHistory() {
-    // Rough: 1 token ≈ 4 chars
-    const estimateTokens = (msgs) => msgs.reduce((sum, m) => sum + Math.ceil(m.content.length / 4), 0);
+  async _buildSystemPrompt(userMessage, overridePrompt) {
+    const parts = [];
+    const soulPrompt = formatSoulSystemPrompt();
+    if (soulPrompt) parts.push(soulPrompt);
+    if (overridePrompt || this.systemPrompt) parts.push(overridePrompt || this.systemPrompt);
+
+    const summary = this.sessionMemory.getSummary();
+    if (summary) {
+      parts.push(`Session summary:\n${summary}`);
+    }
 
-    while (this.conversationHistory.length > 2 && estimateTokens(this.conversationHistory) > this.maxHistoryTokens) {
-      // Remove oldest pair (user + assistant)
-      this.conversationHistory.splice(0, 2);
+    const relevantMemories = await searchMemories(userMessage);
+    if (relevantMemories.length > 0) {
+      parts.push(
+        `Relevant persistent memories:\n${relevantMemories
+          .slice(0, this.maxRelevantMemories)
+          .map((memory) => `- [${memory.category}] ${memory.content}`)
+          .join('\n')}`
+      );
     }
+
+    return parts.filter(Boolean).join('\n\n');
   }
 }
 
-// ──────────────────────────────────────────────────
-// FACTORY
-// ──────────────────────────────────────────────────
-
-/**
- * Create and initialize an LLM engine
- */
 export async function createLLM(opts = {}) {
   const engine = new LLMEngine(opts);
   await engine.init(opts.vaultPassword);
   return engine;
 }
 
-/**
- * Quick one-shot LLM call (auto-resolves provider/key)
- */
 export async function ask(prompt, opts = {}) {
   const engine = await createLLM(opts);
   return engine.complete(prompt, opts);

package/src/memory/index.js

@@ -0,0 +1,275 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+
+const MEMORY_DIR = join(homedir(), '.darksol', 'memory');
+const MEMORY_FILE = join(MEMORY_DIR, 'memory.json');
+const MEMORY_CATEGORIES = new Set(['preference', 'fact', 'decision', 'lesson']);
+const MEMORY_PATTERNS = [
+  { regex: /\b(i prefer|i like|i usually|my favorite)\b/i, category: 'preference' },
+  { regex: /\b(remember that|remember this|my address is|i live at|my phone number is)\b/i, category: 'fact' },
+  { regex: /\b(always|never|from now on|do not|don't)\b/i, category: 'decision' },
+  { regex: /\b(i learned|lesson|next time|that means)\b/i, category: 'lesson' },
+];
+
+/**
+ * Ensure the memory directory and file exist.
+ * @returns {Promise<void>}
+ */
+async function ensureMemoryStore() {
+  await mkdir(MEMORY_DIR, { recursive: true });
+  if (!existsSync(MEMORY_FILE)) {
+    await writeFile(MEMORY_FILE, '[]\n', 'utf8');
+  }
+}
+
+/**
+ * Load all persistent memories from disk.
+ * @returns {Promise<Array<{id: string, content: string, category: string, timestamp: string, source: string}>>}
+ */
+export async function loadMemories() {
+  await ensureMemoryStore();
+
+  try {
+    const raw = await readFile(MEMORY_FILE, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Persist the full memory list.
+ * @param {Array<object>} memories
+ * @returns {Promise<void>}
+ */
+async function writeMemories(memories) {
+  await ensureMemoryStore();
+  await writeFile(MEMORY_FILE, `${JSON.stringify(memories, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Save a memory item to disk.
+ * @param {string} content
+ * @param {'preference'|'fact'|'decision'|'lesson'} category
+ * @param {string} [source='user']
+ * @returns {Promise<object|null>}
+ */
+export async function saveMemory(content, category, source = 'user') {
+  const trimmed = String(content || '').trim();
+  if (!trimmed) return null;
+
+  const finalCategory = MEMORY_CATEGORIES.has(category) ? category : 'fact';
+  const memories = await loadMemories();
+  const duplicate = memories.find((memory) => memory.content.toLowerCase() === trimmed.toLowerCase());
+  if (duplicate) return duplicate;
+
+  const entry = {
+    id: randomUUID(),
+    content: trimmed,
+    category: finalCategory,
+    timestamp: new Date().toISOString(),
+    source,
+  };
+
+  memories.push(entry);
+  await writeMemories(memories);
+  return entry;
+}
+
+/**
+ * Search memories by a text query.
+ * @param {string} query
+ * @returns {Promise<Array<object>>}
+ */
+export async function searchMemories(query) {
+  const trimmed = String(query || '').trim().toLowerCase();
+  if (!trimmed) return [];
+
+  const terms = trimmed.split(/\s+/).filter(Boolean);
+  const memories = await loadMemories();
+
+  return memories
+    .map((memory) => {
+      const haystack = `${memory.content} ${memory.category} ${memory.source}`.toLowerCase();
+      const score = terms.reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0);
+      return { memory, score };
+    })
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return new Date(b.memory.timestamp).getTime() - new Date(a.memory.timestamp).getTime();
+    })
+    .map(({ memory }) => memory);
+}
+
+/**
+ * Return the most recent N memories.
+ * @param {number} [n=10]
+ * @returns {Promise<Array<object>>}
+ */
+export async function getRecentMemories(n = 10) {
+  const memories = await loadMemories();
+  return [...memories]
+    .sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())
+    .slice(0, n);
+}
+
+/**
+ * Remove memories older than maxAge milliseconds.
+ * @param {number} maxAge
+ * @returns {Promise<number>}
+ */
+export async function pruneMemories(maxAge) {
+  if (!Number.isFinite(maxAge) || maxAge <= 0) return 0;
+
+  const cutoff = Date.now() - maxAge;
+  const memories = await loadMemories();
+  const kept = memories.filter((memory) => new Date(memory.timestamp).getTime() >= cutoff);
+  await writeMemories(kept);
+  return memories.length - kept.length;
+}
+
+/**
+ * Remove all persistent memories.
+ * @returns {Promise<void>}
+ */
+export async function clearMemories() {
+  await ensureMemoryStore();
+  await writeMemories([]);
+}
+
+/**
+ * Export memories to a JSON file and return its path.
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+export async function exportMemories(filePath) {
+  const memories = await loadMemories();
+  await writeFile(filePath, `${JSON.stringify(memories, null, 2)}\n`, 'utf8');
+  return filePath;
+}
+
+/**
+ * Attempt to extract memory-worthy statements from a message.
+ * @param {string} content
+ * @param {string} [source='user']
+ * @returns {Promise<Array<object>>}
+ */
+export async function extractMemories(content, source = 'user') {
+  const text = String(content || '').trim();
+  if (!text) return [];
+
+  const segments = text
+    .split(/[\n\r]+|(?<=[.!?])\s+/)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+
+  const saved = [];
+  for (const segment of segments) {
+    for (const pattern of MEMORY_PATTERNS) {
+      if (pattern.regex.test(segment)) {
+        const memory = await saveMemory(segment, pattern.category, source);
+        if (memory) saved.push(memory);
+        break;
+      }
+    }
+  }
+
+  return saved;
+}
+
+/**
+ * In-session conversation memory with rolling compaction.
+ */
+export class SessionMemory {
+  /**
+   * @param {{maxTurns?: number}} [opts]
+   */
+  constructor(opts = {}) {
+    this.maxTurns = opts.maxTurns || 20;
+    this.messages = [];
+    this.summary = '';
+  }
+
+  /**
+   * Add a new turn to the current session.
+   * @param {'user'|'assistant'|'system'} role
+   * @param {string} content
+   * @returns {void}
+   */
+  addTurn(role, content) {
+    const trimmed = String(content || '').trim();
+    if (!trimmed) return;
+    this.messages.push({ role, content: trimmed });
+  }
+
+  /**
+   * Return recent conversation turns.
+   * @returns {Array<{role: string, content: string}>}
+   */
+  getContext() {
+    return [...this.messages];
+  }
+
+  /**
+   * Return the current summary, if one exists.
+   * @returns {string}
+   */
+  getSummary() {
+    return this.summary;
+  }
+
+  /**
+   * Clear all session memory.
+   * @returns {void}
+   */
+  clear() {
+    this.messages = [];
+    this.summary = '';
+  }
+
+  /**
+   * Compact older turns into a short summary with help from the LLM.
+   * @param {{complete: (prompt: string, opts?: object) => Promise<{content: string}>}} llm
+   * @returns {Promise<void>}
+   */
+  async compact(llm) {
+    if (this.messages.length <= this.maxTurns) return;
+
+    const overflow = this.messages.length - this.maxTurns;
+    const batchSize = Math.max(overflow, Math.ceil(this.maxTurns / 2));
+    const olderMessages = this.messages.splice(0, batchSize);
+    const transcript = olderMessages
+      .map((message) => `${message.role.toUpperCase()}: ${message.content}`)
+      .join('\n');
+
+    const prompt = [
+      'Summarize this conversation context for future replies.',
+      'Preserve preferences, decisions, constraints, open tasks, and factual details.',
+      'Keep it under 180 words.',
+      this.summary ? `Existing summary:\n${this.summary}` : '',
+      `Conversation to compact:\n${transcript}`,
+    ].filter(Boolean).join('\n\n');
+
+    try {
+      const result = await llm.complete(prompt, {
+        ephemeral: true,
+        skipContext: true,
+        skipMemoryExtraction: true,
+      });
+      this.summary = String(result.content || '').trim() || this.summary;
+    } catch {
+      const fallback = olderMessages
+        .slice(-4)
+        .map((message) => `${message.role}: ${message.content}`)
+        .join(' | ');
+      this.summary = [this.summary, fallback].filter(Boolean).join(' | ').slice(-1200);
+    }
+  }
+}
+
+export { MEMORY_DIR, MEMORY_FILE };

package/src/setup/wizard.js

@@ -4,6 +4,7 @@ import { showSection, showDivider } from '../ui/banner.js';
 import { success, error, warn, info, kvDisplay } from '../ui/components.js';
 import { getConfig, setConfig } from '../config/store.js';
 import { addKeyDirect, hasKey, hasAnyLLM, SERVICES } from '../config/keys.js';
+import { hasSoul, runSoulSetup } from '../soul/index.js';
 import { createServer } from 'http';
 import open from 'open';
 import crypto from 'crypto';
@@ -18,7 +19,7 @@ import crypto from 'crypto';
 export function isFirstRun() {
   const llmReady = hasAnyLLM();
   const setupDone = getConfig('setupComplete');
-  return !llmReady && !setupDone;
+  return (!llmReady && !setupDone) || !hasSoul();
 }
 
 /**
@@ -42,7 +43,10 @@ export async function runSetupWizard(opts = {}) {
 
   showDivider();
 
-  // Step 1: Choose LLM provider
+  // Step 1: Soul / identity
+  await runSoulSetup({ showBanner: false, reset: force });
+
+  // Step 2: Choose LLM provider
   const { provider } = await inquirer.prompt([{
     type: 'list',
     name: 'provider',
@@ -69,7 +73,7 @@ export async function runSetupWizard(opts = {}) {
     await setupCloudProvider(provider);
   }
 
-  // Step 2: Chain selection
+  // Step 3: Chain selection
   console.log('');
   const { chain } = await inquirer.prompt([{
     type: 'list',
@@ -87,7 +91,7 @@ export async function runSetupWizard(opts = {}) {
   setConfig('chain', chain);
   success(`Chain set to ${chain}`);
 
-  // Step 3: Wallet
+  // Step 4: Wallet
   console.log('');
   const { wantWallet } = await inquirer.prompt([{
     type: 'confirm',

package/src/soul/index.js

@@ -0,0 +1,139 @@
+import inquirer from 'inquirer';
+import { getConfig, setConfig, deleteConfig } from '../config/store.js';
+import { theme } from '../ui/theme.js';
+import { showMiniBanner, showSection } from '../ui/banner.js';
+import { kvDisplay, info, success, warn } from '../ui/components.js';
+
+const TONE_CHOICES = ['professional', 'casual', 'hacker', 'friendly', 'sarcastic', 'custom'];
+
+/**
+ * Return the current persisted soul configuration.
+ * @returns {{userName: string, agentName: string, tone: string, createdAt: string}}
+ */
+export function getSoul() {
+  const soul = getConfig('soul') || {};
+  return {
+    userName: soul.userName || '',
+    agentName: soul.agentName || 'Darksol',
+    tone: soul.tone || '',
+    createdAt: soul.createdAt || '',
+  };
+}
+
+/**
+ * Whether a usable soul profile has been created.
+ * @returns {boolean}
+ */
+export function hasSoul() {
+  const soul = getSoul();
+  return Boolean(soul.userName && soul.agentName && soul.tone);
+}
+
+/**
+ * Generate a soul-derived system prompt for LLM calls.
+ * @returns {string}
+ */
+export function formatSystemPrompt() {
+  if (!hasSoul()) return '';
+
+  const soul = getSoul();
+  return [
+    `You are ${soul.agentName}, the user's persistent DARKSOL Terminal agent.`,
+    `Address the user as ${soul.userName}.`,
+    `Maintain a ${soul.tone} tone unless the user explicitly asks for a different style.`,
+    'Stay concise, terminal-native, and practical.',
+    'Preserve the deep black DARKSOL aesthetic: sharp, calm, and low-noise.',
+  ].join('\n');
+}
+
+/**
+ * Pretty-print the current soul configuration.
+ * @returns {void}
+ */
+export function displaySoul() {
+  const soul = getSoul();
+
+  showMiniBanner();
+  showSection('SOUL CONFIG');
+  kvDisplay([
+    ['User', soul.userName || theme.dim('(not set)')],
+    ['Agent', soul.agentName],
+    ['Tone', soul.tone || theme.dim('(not set)')],
+    ['Created', soul.createdAt || theme.dim('(not set)')],
+  ]);
+  console.log('');
+}
+
+/**
+ * Interactive soul setup flow.
+ * @param {{showBanner?: boolean, reset?: boolean}} opts
+ * @returns {Promise<{userName: string, agentName: string, tone: string, createdAt: string}>}
+ */
+export async function runSoulSetup(opts = {}) {
+  const currentSoul = getSoul();
+
+  if (opts.showBanner !== false) {
+    showMiniBanner();
+    showSection(hasSoul() && !opts.reset ? 'UPDATE SOUL' : 'SOUL SETUP');
+    console.log(theme.dim('  Shape how DARKSOL knows you and how your agent should speak.'));
+    console.log('');
+  }
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'userName',
+      message: 'What should I call you?',
+      default: currentSoul.userName || undefined,
+      validate: (value) => value.trim().length > 0 || 'Name is required',
+    },
+    {
+      type: 'input',
+      name: 'agentName',
+      message: 'Name your agent:',
+      default: currentSoul.agentName || 'Darksol',
+      validate: (value) => value.trim().length > 0 || 'Agent name is required',
+    },
+    {
+      type: 'list',
+      name: 'tonePreset',
+      message: 'Agent tone:',
+      choices: TONE_CHOICES.map((tone) => ({
+        name: tone === 'custom' ? 'custom' : tone,
+        value: tone,
+      })),
+      default: TONE_CHOICES.includes(currentSoul.tone) ? currentSoul.tone : 'professional',
+    },
+    {
+      type: 'input',
+      name: 'customTone',
+      message: 'Describe the tone:',
+      when: (answers) => answers.tonePreset === 'custom',
+      default: TONE_CHOICES.includes(currentSoul.tone) ? undefined : currentSoul.tone || undefined,
+      validate: (value) => value.trim().length > 0 || 'Tone is required',
+    },
+  ]);
+
+  const soul = {
+    userName: answers.userName.trim(),
+    agentName: answers.agentName.trim() || 'Darksol',
+    tone: (answers.tonePreset === 'custom' ? answers.customTone : answers.tonePreset).trim(),
+    createdAt: currentSoul.createdAt && !opts.reset ? currentSoul.createdAt : new Date().toISOString(),
+  };
+
+  setConfig('soul', soul);
+  success(`Soul bound: ${soul.agentName} → ${soul.userName}`);
+  info(`Tone locked to ${soul.tone}`);
+  console.log('');
+
+  return soul;
+}
+
+/**
+ * Reset persisted soul configuration.
+ * @returns {void}
+ */
+export function resetSoul() {
+  deleteConfig('soul');
+  warn('Soul profile cleared.');
+}

package/src/web/commands.js

@@ -1,6 +1,8 @@
 import fetch from 'node-fetch';
 import { getConfig, setConfig } from '../config/store.js';
 import { hasKey, hasAnyLLM, getKeyAuto, addKeyDirect, SERVICES } from '../config/keys.js';
+import { getRecentMemories } from '../memory/index.js';
+import { getSoul, hasSoul } from '../soul/index.js';
 import { ethers } from 'ethers';
 import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'fs';
 import { join, dirname } from 'path';
@@ -782,6 +784,7 @@ export function getAIStatus() {
 
   const providers = ['openai', 'anthropic', 'openrouter', 'ollama', 'bankr'];
   const connected = providers.filter(p => hasKey(p));
+  const soul = hasSoul() ? getSoul() : null;
 
   if (connected.length > 0) {
     const names = connected.map(p => SERVICES[p]?.name || p).join(', ');
@@ -1802,6 +1805,8 @@ async function cmdAI(args, ws) {
       const chain = getConfig('chain') || 'base';
       const wallet = getConfig('activeWallet') || '(not set)';
       const slippage = getConfig('slippage') || 0.5;
+      const soul = hasSoul() ? getSoul() : null;
+      const recentMemories = await getRecentMemories(3);
 
       engine.setSystemPrompt(`You are DARKSOL Terminal's AI trading assistant running in a web terminal.
 
@@ -1818,6 +1823,10 @@ USER CONTEXT:
 - Active wallet: ${wallet}
 - Slippage: ${slippage}%
 - Supported chains: Base (default), Ethereum, Polygon, Arbitrum, Optimism
+- Soul user: ${soul?.userName || '(unknown)'}
+- Soul agent: ${soul?.agentName || 'Darksol'}
+- Soul tone: ${soul?.tone || 'practical'}
+- Recent persistent memories loaded: ${recentMemories.length}
 
 RULES:
 - Be concise — this is a terminal, not a blog
@@ -1839,6 +1848,9 @@ COMMAND REFERENCE:
 
       chatEngines.set(ws, engine);
       ws.sendLine(`  ${ANSI.green}● AI connected${ANSI.reset} ${ANSI.dim}(${engine.provider}/${engine.model})${ANSI.reset}`);
+      if (soul) {
+        ws.sendLine(`  ${ANSI.dim}${soul.agentName} is live for ${soul.userName} with ${soul.tone} tone.${ANSI.reset}`);
+      }
       ws.sendLine('');
     } catch (err) {
       ws.sendLine(`  ${ANSI.red}✗ AI initialization failed: ${err.message}${ANSI.reset}`);

package/src/web/server.js

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import open from 'open';
 import { theme } from '../ui/theme.js';
+import { getRecentMemories } from '../memory/index.js';
+import { getSoul, hasSoul } from '../soul/index.js';
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const { version: PKG_VERSION } = require('../../package.json');
@@ -89,6 +91,19 @@ export async function startWebShell(opts = {}) {
       data: getBanner(),
     }));
 
+    if (hasSoul()) {
+      const soul = getSoul();
+      getRecentMemories(3).then((memories) => {
+        const memoryHint = memories.length > 0
+          ? `\r\n  \x1b[38;2;102;102;102m${soul.agentName} loaded ${memories.length} recent memories.\x1b[0m`
+          : '';
+        ws.send(JSON.stringify({
+          type: 'output',
+          data: `  \x1b[38;2;255;215;0mWelcome back, ${soul.userName}.\x1b[0m\r\n  \x1b[38;2;102;102;102m${soul.agentName} is online with a ${soul.tone} tone.\x1b[0m${memoryHint}\r\n\r\n`,
+        }));
+      }).catch(() => {});
+    }
+
     // AI connection check right after banner
     const aiStatus = getAIStatus();
     ws.send(JSON.stringify({