memshell 0.2.0 → 0.3.0

package/bin/mem.js

@@ -1,89 +1,163 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const mem = require('../src/index');
 
 const args = process.argv.slice(2);
 const cmd = args[0];
-const rest = args.slice(1).join(' ');
 
 const HELP = `
-  mem.sh — persistent memory for AI agents
+  \x1b[1mmem.sh\x1b[0m — persistent memory for AI agents
 
-  Usage:
-    mem set <text>          Store a memory
-    mem recall <query>      Semantic recall
-    mem list                List all memories
-    mem forget <id>         Delete a memory by ID
-    mem clear               Wipe all memories
-    mem serve [--port N]    Start API server
+  \x1b[36mUsage:\x1b[0m
+    memshell set <text>              Store a memory
+    memshell recall <query>          Semantic recall
+    memshell list                    List all memories
+    memshell forget <id>             Delete a memory by ID
+    memshell clear                   Wipe all memories
+    memshell important <id>          Boost memory importance
+    memshell stats                   Show memory statistics
+    memshell export                  Export all memories as JSON
+    memshell import <file.json>      Import memories from JSON
+    memshell serve [--port N]        Start API server
 
-  Options:
+  \x1b[36mOptions:\x1b[0m
     --agent <name>          Agent namespace
     --api <url>             Use remote API instead of local
     --key <key>             API key for remote server
+    --tags <t1,t2>          Tags (comma-separated)
+    --top <N>               Return top N results only
+    --embeddings            Enable OpenAI embeddings (needs OPENAI_API_KEY)
 
-  Examples:
-    mem set "user prefers dark mode"
-    mem recall "what theme?"
-    mem list
-    mem forget 3
+  \x1b[36mExamples:\x1b[0m
+    memshell set "user prefers dark mode" --tags preferences,ui
+    memshell recall "what theme?" --tags preferences --top 3
+    memshell important 5
+    memshell stats
+    memshell export > backup.json
+    memshell import backup.json
 `;
 
 // Parse flags
 function flag(name) {
   const i = args.indexOf('--' + name);
   if (i === -1) return null;
-  return args[i + 1] || true;
+  if (i + 1 < args.length && !args[i + 1].startsWith('--')) return args[i + 1];
+  return true;
+}
+
+function hasFlag(name) {
+  return args.includes('--' + name);
+}
+
+function getTextArgs() {
+  return args.slice(1).filter(a => !a.startsWith('--') && (args.indexOf(a) === 0 || !['--agent', '--api', '--key', '--tags', '--top', '--port'].includes(args[args.indexOf(a) - 1]))).join(' ').replace(/^["']|["']$/g, '');
+}
+
+// Smarter text extraction: skip flag values
+function getText() {
+  const skip = new Set(['--agent', '--api', '--key', '--tags', '--top', '--port']);
+  const parts = [];
+  let i = 1; // skip command
+  while (i < args.length) {
+    if (skip.has(args[i])) { i += 2; continue; }
+    if (args[i] === '--embeddings') { i++; continue; }
+    if (args[i].startsWith('--')) { i++; continue; }
+    parts.push(args[i]);
+    i++;
+  }
+  return parts.join(' ').replace(/^["']|["']$/g, '');
 }
 
 async function main() {
   const agent = flag('agent') || 'default';
   const api = flag('api');
   const key = flag('key');
+  const tags = flag('tags') || '';
+  const top = flag('top') ? parseInt(flag('top')) : null;
+  const useEmbeddings = hasFlag('embeddings');
 
-  if (api) mem.configure({ api, key, agent });
-  else mem.configure({ agent });
+  const configOpts = { agent };
+  if (api) { configOpts.api = api; configOpts.key = key; }
+  if (useEmbeddings) { configOpts.openaiKey = process.env.OPENAI_API_KEY; }
 
-  const opts = { agent };
+  mem.configure(configOpts);
+
+  const opts = { agent, tags, top };
 
   switch (cmd) {
     case 'set': case 's': case 'save': case 'remember': {
-      const text = args.slice(1).filter(a => !a.startsWith('--')).join(' ').replace(/^["']|["']$/g, '');
-      if (!text) return console.log('Usage: mem set <text>');
-      const r = await mem.set(text, opts);
-      console.log(`✓ Stored (id: ${r.id})`);
+      const text = getText();
+      if (!text) return console.log('Usage: memshell set <text>');
+      const r = await mem.set(text, { ...opts, tags });
+      console.log(`\x1b[32m✓\x1b[0m Stored (id: \x1b[1m${r.id}\x1b[0m)${tags ? ` [tags: ${tags}]` : ''}`);
       break;
     }
     case 'recall': case 'r': case 'search': case 'q': {
-      const query = args.slice(1).filter(a => !a.startsWith('--')).join(' ').replace(/^["']|["']$/g, '');
-      if (!query) return console.log('Usage: mem recall <query>');
+      const query = getText();
+      if (!query) return console.log('Usage: memshell recall <query>');
       const results = await mem.recall(query, opts);
-      if (!results.length) return console.log('No memories found.');
+      if (!results.length) return console.log('\x1b[33mNo memories found.\x1b[0m');
       for (const r of results) {
-        console.log(`  [${r.id}] ${r.text} (score: ${r.score})`);
+        const tagStr = r.tags ? ` \x1b[35m[${r.tags}]\x1b[0m` : '';
+        console.log(`  \x1b[36m[${r.id}]\x1b[0m ${r.text} \x1b[33m(score: ${r.score})\x1b[0m${tagStr}`);
       }
       break;
     }
     case 'list': case 'ls': case 'l': {
       const all = await mem.list(opts);
-      if (!all.length) return console.log('No memories stored.');
+      if (!all.length) return console.log('\x1b[33mNo memories stored.\x1b[0m');
       for (const r of all) {
-        console.log(`  [${r.id}] ${r.text}  (${r.created_at})`);
+        const tagStr = r.tags ? ` \x1b[35m[${r.tags}]\x1b[0m` : '';
+        const imp = r.importance !== 1.0 ? ` \x1b[33m★${r.importance.toFixed(1)}\x1b[0m` : '';
+        console.log(`  \x1b[36m[${r.id}]\x1b[0m ${r.text}${tagStr}${imp}  \x1b[2m(${r.created_at})\x1b[0m`);
       }
-      console.log(`\n  ${all.length} memor${all.length === 1 ? 'y' : 'ies'}`);
+      console.log(`\n  \x1b[1m${all.length}\x1b[0m memor${all.length === 1 ? 'y' : 'ies'}`);
       break;
     }
     case 'forget': case 'delete': case 'rm': {
       const id = args[1];
-      if (!id) return console.log('Usage: mem forget <id>');
+      if (!id) return console.log('Usage: memshell forget <id>');
       await mem.forget(id);
-      console.log(`✓ Forgotten (id: ${id})`);
+      console.log(`\x1b[32m✓\x1b[0m Forgotten (id: ${id})`);
       break;
     }
     case 'clear': case 'wipe': case 'reset': {
       await mem.clear(opts);
-      console.log('✓ All memories cleared');
+      console.log('\x1b[32m✓\x1b[0m All memories cleared');
+      break;
+    }
+    case 'important': case 'boost': {
+      const id = args[1];
+      if (!id) return console.log('Usage: memshell important <id>');
+      const r = await mem.important(Number(id));
+      if (!r) return console.log('\x1b[31mMemory not found.\x1b[0m');
+      console.log(`\x1b[32m✓\x1b[0m Boosted memory ${r.id} → importance: \x1b[1m${r.importance.toFixed(1)}\x1b[0m`);
+      break;
+    }
+    case 'stats': {
+      const s = await mem.stats(opts);
+      console.log(`\n  \x1b[1m🧠 Memory Stats\x1b[0m`);
+      console.log(`  Total:        \x1b[36m${s.total}\x1b[0m`);
+      console.log(`  Oldest:       ${s.oldest || 'n/a'}`);
+      console.log(`  Newest:       ${s.newest || 'n/a'}`);
+      console.log(`  Avg importance: \x1b[33m${s.avg_importance}\x1b[0m\n`);
+      break;
+    }
+    case 'export': {
+      const data = await mem.exportAll(opts);
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    case 'import': {
+      const file = args[1];
+      if (!file) return console.log('Usage: memshell import <file.json>');
+      const raw = fs.readFileSync(path.resolve(file), 'utf8');
+      const data = JSON.parse(raw);
+      const r = await mem.importAll(Array.isArray(data) ? data : data.memories || []);
+      console.log(`\x1b[32m✓\x1b[0m Imported ${r.imported} memories`);
       break;
     }
     case 'serve': case 'server': {
@@ -91,6 +165,7 @@ async function main() {
       const authKey = flag('key') || process.env.MEM_KEY || '';
       process.env.MEM_PORT = port;
       if (authKey) process.env.MEM_KEY = authKey;
+      if (useEmbeddings) process.env.MEM_USE_EMBEDDINGS = '1';
       require('../server');
       break;
     }
@@ -99,4 +174,4 @@ async function main() {
   }
 }
 
-main().catch(e => { console.error('Error:', e.message); process.exit(1); });
+main().catch(e => { console.error('\x1b[31mError:\x1b[0m', e.message); process.exit(1); });

package/bin/memshell.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const mem = require('../src/index');
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+const HELP = `
+  \x1b[1mmem.sh\x1b[0m — persistent memory for AI agents
+
+  \x1b[36mUsage:\x1b[0m
+    memshell set <text>              Store a memory
+    memshell recall <query>          Semantic recall
+    memshell list                    List all memories
+    memshell forget <id>             Delete a memory by ID
+    memshell clear                   Wipe all memories
+    memshell important <id>          Boost memory importance
+    memshell stats                   Show memory statistics
+    memshell export                  Export all memories as JSON
+    memshell import <file.json>      Import memories from JSON
+    memshell serve [--port N]        Start API server
+
+  \x1b[36mOptions:\x1b[0m
+    --agent <name>          Agent namespace
+    --api <url>             Use remote API instead of local
+    --key <key>             API key for remote server
+    --tags <t1,t2>          Tags (comma-separated)
+    --top <N>               Return top N results only
+    --embeddings            Enable OpenAI embeddings (needs OPENAI_API_KEY)
+
+  \x1b[36mExamples:\x1b[0m
+    memshell set "user prefers dark mode" --tags preferences,ui
+    memshell recall "what theme?" --tags preferences --top 3
+    memshell important 5
+    memshell stats
+    memshell export > backup.json
+    memshell import backup.json
+`;
+
+// Parse flags
+function flag(name) {
+  const i = args.indexOf('--' + name);
+  if (i === -1) return null;
+  if (i + 1 < args.length && !args[i + 1].startsWith('--')) return args[i + 1];
+  return true;
+}
+
+function hasFlag(name) {
+  return args.includes('--' + name);
+}
+
+function getTextArgs() {
+  return args.slice(1).filter(a => !a.startsWith('--') && (args.indexOf(a) === 0 || !['--agent', '--api', '--key', '--tags', '--top', '--port'].includes(args[args.indexOf(a) - 1]))).join(' ').replace(/^["']|["']$/g, '');
+}
+
+// Smarter text extraction: skip flag values
+function getText() {
+  const skip = new Set(['--agent', '--api', '--key', '--tags', '--top', '--port']);
+  const parts = [];
+  let i = 1; // skip command
+  while (i < args.length) {
+    if (skip.has(args[i])) { i += 2; continue; }
+    if (args[i] === '--embeddings') { i++; continue; }
+    if (args[i].startsWith('--')) { i++; continue; }
+    parts.push(args[i]);
+    i++;
+  }
+  return parts.join(' ').replace(/^["']|["']$/g, '');
+}
+
+async function main() {
+  const agent = flag('agent') || 'default';
+  const api = flag('api');
+  const key = flag('key');
+  const tags = flag('tags') || '';
+  const top = flag('top') ? parseInt(flag('top')) : null;
+  const useEmbeddings = hasFlag('embeddings');
+
+  const configOpts = { agent };
+  if (api) { configOpts.api = api; configOpts.key = key; }
+  if (useEmbeddings) { configOpts.openaiKey = process.env.OPENAI_API_KEY; }
+
+  mem.configure(configOpts);
+
+  const opts = { agent, tags, top };
+
+  switch (cmd) {
+    case 'set': case 's': case 'save': case 'remember': {
+      const text = getText();
+      if (!text) return console.log('Usage: memshell set <text>');
+      const r = await mem.set(text, { ...opts, tags });
+      console.log(`\x1b[32m✓\x1b[0m Stored (id: \x1b[1m${r.id}\x1b[0m)${tags ? ` [tags: ${tags}]` : ''}`);
+      break;
+    }
+    case 'recall': case 'r': case 'search': case 'q': {
+      const query = getText();
+      if (!query) return console.log('Usage: memshell recall <query>');
+      const results = await mem.recall(query, opts);
+      if (!results.length) return console.log('\x1b[33mNo memories found.\x1b[0m');
+      for (const r of results) {
+        const tagStr = r.tags ? ` \x1b[35m[${r.tags}]\x1b[0m` : '';
+        console.log(`  \x1b[36m[${r.id}]\x1b[0m ${r.text} \x1b[33m(score: ${r.score})\x1b[0m${tagStr}`);
+      }
+      break;
+    }
+    case 'list': case 'ls': case 'l': {
+      const all = await mem.list(opts);
+      if (!all.length) return console.log('\x1b[33mNo memories stored.\x1b[0m');
+      for (const r of all) {
+        const tagStr = r.tags ? ` \x1b[35m[${r.tags}]\x1b[0m` : '';
+        const imp = r.importance !== 1.0 ? ` \x1b[33m★${r.importance.toFixed(1)}\x1b[0m` : '';
+        console.log(`  \x1b[36m[${r.id}]\x1b[0m ${r.text}${tagStr}${imp}  \x1b[2m(${r.created_at})\x1b[0m`);
+      }
+      console.log(`\n  \x1b[1m${all.length}\x1b[0m memor${all.length === 1 ? 'y' : 'ies'}`);
+      break;
+    }
+    case 'forget': case 'delete': case 'rm': {
+      const id = args[1];
+      if (!id) return console.log('Usage: memshell forget <id>');
+      await mem.forget(id);
+      console.log(`\x1b[32m✓\x1b[0m Forgotten (id: ${id})`);
+      break;
+    }
+    case 'clear': case 'wipe': case 'reset': {
+      await mem.clear(opts);
+      console.log('\x1b[32m✓\x1b[0m All memories cleared');
+      break;
+    }
+    case 'important': case 'boost': {
+      const id = args[1];
+      if (!id) return console.log('Usage: memshell important <id>');
+      const r = await mem.important(Number(id));
+      if (!r) return console.log('\x1b[31mMemory not found.\x1b[0m');
+      console.log(`\x1b[32m✓\x1b[0m Boosted memory ${r.id} → importance: \x1b[1m${r.importance.toFixed(1)}\x1b[0m`);
+      break;
+    }
+    case 'stats': {
+      const s = await mem.stats(opts);
+      console.log(`\n  \x1b[1m🧠 Memory Stats\x1b[0m`);
+      console.log(`  Total:        \x1b[36m${s.total}\x1b[0m`);
+      console.log(`  Oldest:       ${s.oldest || 'n/a'}`);
+      console.log(`  Newest:       ${s.newest || 'n/a'}`);
+      console.log(`  Avg importance: \x1b[33m${s.avg_importance}\x1b[0m\n`);
+      break;
+    }
+    case 'export': {
+      const data = await mem.exportAll(opts);
+      console.log(JSON.stringify(data, null, 2));
+      break;
+    }
+    case 'import': {
+      const file = args[1];
+      if (!file) return console.log('Usage: memshell import <file.json>');
+      const raw = fs.readFileSync(path.resolve(file), 'utf8');
+      const data = JSON.parse(raw);
+      const r = await mem.importAll(Array.isArray(data) ? data : data.memories || []);
+      console.log(`\x1b[32m✓\x1b[0m Imported ${r.imported} memories`);
+      break;
+    }
+    case 'serve': case 'server': {
+      const port = flag('port') || 3456;
+      const authKey = flag('key') || process.env.MEM_KEY || '';
+      process.env.MEM_PORT = port;
+      if (authKey) process.env.MEM_KEY = authKey;
+      if (useEmbeddings) process.env.MEM_USE_EMBEDDINGS = '1';
+      require('../server');
+      break;
+    }
+    default:
+      console.log(HELP);
+  }
+}
+
+main().catch(e => { console.error('\x1b[31mError:\x1b[0m', e.message); process.exit(1); });

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "memshell",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Persistent memory for AI agents. Like localStorage but for LLMs.",
   "main": "src/index.js",
   "bin": {
-    "memshell": "./bin/mem.js"
+    "memshell": "bin/memshell.js"
   },
   "scripts": {
     "start": "node server.js",
@@ -25,7 +25,8 @@
   "author": "justedv",
   "license": "MIT",
   "dependencies": {
-    "express": "^4.18.2"
+    "express": "^4.18.2",
+    "sql.js": "^1.11.0"
   },
   "repository": {
     "type": "git",

package/server.js

@@ -6,12 +6,20 @@ const { LocalStore } = require('./src/index');
 const app = express();
 app.use(express.json());
 
-const store = new LocalStore();
+const storeOpts = {};
+if (process.env.MEM_USE_EMBEDDINGS && process.env.OPENAI_API_KEY) {
+  storeOpts.openaiKey = process.env.OPENAI_API_KEY;
+}
+const store = new LocalStore(undefined, storeOpts);
 const PORT = process.env.MEM_PORT || 3456;
 const AUTH_KEY = process.env.MEM_KEY || '';
 
+// Ensure store is initialized
+let initPromise = store.init();
+
 // Auth middleware
-app.use('/mem', (req, res, next) => {
+app.use('/mem', async (req, res, next) => {
+  await initPromise;
   if (AUTH_KEY && req.headers['x-mem-key'] !== AUTH_KEY) {
     return res.status(401).json({ error: 'Invalid API key' });
   }
@@ -20,43 +28,72 @@ app.use('/mem', (req, res, next) => {
 });
 
 // Store a memory
-app.post('/mem', (req, res) => {
-  const { text, metadata } = req.body;
+app.post('/mem', async (req, res) => {
+  const { text, tags, importance, metadata } = req.body;
   if (!text) return res.status(400).json({ error: 'text is required' });
-  const result = store.set(text, { agent: req.agent, metadata });
+  const result = await store.set(text, { agent: req.agent, tags: tags || '', importance, metadata });
   res.json(result);
 });
 
 // Semantic recall
-app.get('/mem/recall', (req, res) => {
+app.get('/mem/recall', async (req, res) => {
   const q = req.query.q;
   if (!q) return res.status(400).json({ error: 'q parameter is required' });
   const limit = parseInt(req.query.limit) || 10;
-  const results = store.recall(q, { agent: req.agent, limit });
+  const tags = req.query.tags || '';
+  const top = req.query.top ? parseInt(req.query.top) : null;
+  const results = await store.recall(q, { agent: req.agent, limit, tags, top });
   res.json(results);
 });
 
 // List all
-app.get('/mem/list', (req, res) => {
-  const results = store.list({ agent: req.agent });
+app.get('/mem/list', async (req, res) => {
+  const results = await store.list({ agent: req.agent });
   res.json(results);
 });
 
+// Stats
+app.get('/mem/stats', async (req, res) => {
+  const stats = await store.stats({ agent: req.agent });
+  res.json(stats);
+});
+
+// Export
+app.get('/mem/export', async (req, res) => {
+  const data = await store.exportAll({ agent: req.query.agent });
+  res.json(data);
+});
+
+// Import
+app.post('/mem/import', async (req, res) => {
+  const memories = Array.isArray(req.body) ? req.body : req.body.memories || [];
+  const result = await store.importAll(memories);
+  res.json(result);
+});
+
+// Boost importance
+app.post('/mem/:id/important', async (req, res) => {
+  const result = await store.important(req.params.id);
+  if (!result) return res.status(404).json({ error: 'Memory not found' });
+  res.json(result);
+});
+
 // Delete by id
-app.delete('/mem/:id', (req, res) => {
-  store.forget(req.params.id);
+app.delete('/mem/:id', async (req, res) => {
+  await store.forget(req.params.id);
   res.json({ ok: true, id: req.params.id });
 });
 
 // Clear all for agent
-app.delete('/mem', (req, res) => {
-  store.clear({ agent: req.agent });
+app.delete('/mem', async (req, res) => {
+  await store.clear({ agent: req.agent });
   res.json({ ok: true });
 });
 
 app.listen(PORT, () => {
   console.log(`\n  🧠 mem.sh server running on http://localhost:${PORT}`);
   console.log(`  Auth: ${AUTH_KEY ? 'enabled' : 'disabled'}`);
+  console.log(`  Embeddings: ${storeOpts.openaiKey ? 'OpenAI' : 'TF-IDF'}`);
   console.log();
 });
 

package/src/index.js

@@ -64,75 +64,299 @@ class TfIdf {
   }
 }
 
-// ── JSON File Store ────────────────────────────────────────────
+// ── OpenAI Embeddings ──────────────────────────────────────────
+class OpenAIEmbedder {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+
+  async embed(text) {
+    const body = JSON.stringify({
+      model: 'text-embedding-3-small',
+      input: text
+    });
+    const res = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`
+      },
+      body
+    });
+    if (!res.ok) throw new Error(`OpenAI API error: ${res.status}`);
+    const data = await res.json();
+    return data.data[0].embedding;
+  }
+
+  cosine(a, b) {
+    let dot = 0, magA = 0, magB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+    if (!magA || !magB) return 0;
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  }
+}
+
+// ── SQLite Store (sql.js) ──────────────────────────────────────
 class LocalStore {
-  constructor(dir) {
+  constructor(dir, opts = {}) {
     this.dir = dir || path.join(os.homedir(), '.mem');
-    this.dbPath = path.join(this.dir, 'mem.json');
+    this.dbPath = path.join(this.dir, 'mem.db');
     this.tfidf = new TfIdf();
-    this._data = null;
+    this._db = null;
+    this._SQL = null;
+    this._openaiKey = opts.openaiKey || process.env.OPENAI_API_KEY || null;
+    this._embedder = this._openaiKey ? new OpenAIEmbedder(this._openaiKey) : null;
   }
 
-  _load() {
-    if (this._data) return this._data;
+  _initDb() {
+    if (this._db) return this._db;
+    const initSqlJs = require('sql.js');
+    // sql.js returns a promise, but we need sync init for backward compat
+    // Use the sync factory if available, otherwise we cache
+    if (!this._SQL) {
+      throw new Error('Must call await store.init() before using the store');
+    }
+    return this._db;
+  }
+
+  async init() {
+    if (this._db) return;
+    const initSqlJs = require('sql.js');
+    this._SQL = await initSqlJs();
     fs.mkdirSync(this.dir, { recursive: true });
     try {
-      this._data = JSON.parse(fs.readFileSync(this.dbPath, 'utf8'));
+      const buf = fs.readFileSync(this.dbPath);
+      this._db = new this._SQL.Database(buf);
     } catch {
-      this._data = { nextId: 1, memories: [] };
+      this._db = new this._SQL.Database();
     }
-    return this._data;
+    this._db.run(`CREATE TABLE IF NOT EXISTS memories (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      text TEXT NOT NULL,
+      agent TEXT DEFAULT 'default',
+      embedding TEXT,
+      tags TEXT DEFAULT '',
+      created_at TEXT NOT NULL,
+      importance REAL DEFAULT 1.0
+    )`);
+    this._save();
   }
 
   _save() {
-    fs.writeFileSync(this.dbPath, JSON.stringify(this._data, null, 2));
+    const data = this._db.export();
+    const buf = Buffer.from(data);
+    fs.writeFileSync(this.dbPath, buf);
   }
 
-  set(text, opts = {}) {
-    const data = this._load();
+  _applyDecay(row) {
+    const created = new Date(row.created_at);
+    const now = new Date();
+    const days = (now - created) / (1000 * 60 * 60 * 24);
+    if (days > 30) {
+      const decay = (days - 30) * 0.01;
+      const decayed = Math.max(0.1, row.importance - decay);
+      return decayed;
+    }
+    return row.importance;
+  }
+
+  async set(text, opts = {}) {
+    await this.init();
     const agent = opts.agent || 'default';
-    const entry = {
-      id: data.nextId++,
-      text,
-      agent,
-      created_at: new Date().toISOString(),
-      metadata: opts.metadata || {}
-    };
-    data.memories.push(entry);
+    const tags = opts.tags || '';
+    const importance = opts.importance || 1.0;
+    const created_at = new Date().toISOString();
+
+    let embedding = null;
+    if (this._embedder) {
+      try {
+        const emb = await this._embedder.embed(text);
+        embedding = JSON.stringify(emb);
+      } catch (e) {
+        // fallback: no embedding
+      }
+    }
+
+    this._db.run(
+      'INSERT INTO memories (text, agent, embedding, tags, created_at, importance) VALUES (?, ?, ?, ?, ?, ?)',
+      [text, agent, embedding, tags, created_at, importance]
+    );
+    const id = this._db.exec('SELECT last_insert_rowid() as id')[0].values[0][0];
     this._save();
-    return { id: entry.id, text, agent };
+    return { id, text, agent, tags };
   }
 
-  recall(query, opts = {}) {
-    const data = this._load();
+  async recall(query, opts = {}) {
+    await this.init();
     const agent = opts.agent || 'default';
     const limit = opts.limit || 10;
-    const rows = data.memories.filter(m => m.agent === agent);
-    return this.tfidf.rank(query, rows).slice(0, limit);
+    const top = opts.top || null;
+    const filterTags = opts.tags ? opts.tags.split(',').map(t => t.trim()) : null;
+
+    const stmt = this._db.exec(
+      'SELECT id, text, agent, embedding, tags, created_at, importance FROM memories WHERE agent = ?',
+      [agent]
+    );
+    if (!stmt.length) return [];
+
+    const cols = stmt[0].columns;
+    let rows = stmt[0].values.map(v => {
+      const obj = {};
+      cols.forEach((c, i) => obj[c] = v[i]);
+      return obj;
+    });
+
+    // Filter by tags if specified
+    if (filterTags) {
+      rows = rows.filter(r => {
+        const rTags = (r.tags || '').split(',').map(t => t.trim()).filter(Boolean);
+        return filterTags.some(ft => rTags.includes(ft));
+      });
+    }
+
+    let scored;
+
+    // Try OpenAI embeddings first
+    if (this._embedder) {
+      try {
+        const qEmb = await this._embedder.embed(query);
+        scored = rows.map(row => {
+          let similarity = 0;
+          if (row.embedding) {
+            const emb = JSON.parse(row.embedding);
+            similarity = this._embedder.cosine(qEmb, emb);
+          }
+          const effectiveImportance = this._applyDecay(row);
+          const maxImportance = Math.max(...rows.map(r => this._applyDecay(r)), 1);
+          const normImportance = effectiveImportance / maxImportance;
+          const finalScore = similarity * 0.7 + normImportance * 0.3;
+          return { id: row.id, text: row.text, agent: row.agent, tags: row.tags, created_at: row.created_at, importance: row.importance, score: Math.round(finalScore * 1000) / 1000 };
+        }).filter(d => d.score > 0.01).sort((a, b) => b.score - a.score);
+      } catch {
+        scored = null; // fall through to TF-IDF
+      }
+    }
+
+    if (!scored) {
+      // TF-IDF fallback
+      const tfidfResults = this.tfidf.rank(query, rows);
+      scored = tfidfResults.map(r => {
+        const effectiveImportance = this._applyDecay(r);
+        const maxImportance = Math.max(...rows.map(row => this._applyDecay(row)), 1);
+        const normImportance = effectiveImportance / maxImportance;
+        const similarity = r.score;
+        const finalScore = similarity * 0.7 + normImportance * 0.3;
+        return { ...r, score: Math.round(finalScore * 1000) / 1000 };
+      }).sort((a, b) => b.score - a.score);
+    }
+
+    const resultLimit = top || limit;
+    const results = scored.slice(0, resultLimit);
+
+    // Bump importance for recalled memories
+    for (const r of results) {
+      this._db.run('UPDATE memories SET importance = importance + 0.1 WHERE id = ?', [r.id]);
+    }
+    this._save();
+
+    return results;
   }
 
-  list(opts = {}) {
-    const data = this._load();
+  async list(opts = {}) {
+    await this.init();
     const agent = opts.agent || 'default';
-    return data.memories.filter(m => m.agent === agent).sort((a, b) => b.id - a.id);
+    const stmt = this._db.exec(
+      'SELECT id, text, agent, tags, created_at, importance FROM memories WHERE agent = ? ORDER BY id DESC',
+      [agent]
+    );
+    if (!stmt.length) return [];
+    const cols = stmt[0].columns;
+    return stmt[0].values.map(v => {
+      const obj = {};
+      cols.forEach((c, i) => obj[c] = v[i]);
+      obj.importance = this._applyDecay(obj);
+      return obj;
+    });
   }
 
-  forget(id) {
-    const data = this._load();
-    const numId = Number(id);
-    const before = data.memories.length;
-    data.memories = data.memories.filter(m => m.id !== numId);
+  async forget(id) {
+    await this.init();
+    this._db.run('DELETE FROM memories WHERE id = ?', [Number(id)]);
+    const changes = this._db.getRowsModified();
     this._save();
-    return { changes: before - data.memories.length };
+    return { changes };
   }
 
-  clear(opts = {}) {
-    const data = this._load();
+  async clear(opts = {}) {
+    await this.init();
     const agent = opts.agent || 'default';
-    const before = data.memories.length;
-    data.memories = data.memories.filter(m => m.agent !== agent);
+    this._db.run('DELETE FROM memories WHERE agent = ?', [agent]);
+    const changes = this._db.getRowsModified();
     this._save();
-    return { changes: before - data.memories.length };
+    return { changes };
+  }
+
+  async important(id, boost = 0.5) {
+    await this.init();
+    this._db.run('UPDATE memories SET importance = importance + ? WHERE id = ?', [boost, Number(id)]);
+    this._save();
+    const stmt = this._db.exec('SELECT id, text, importance FROM memories WHERE id = ?', [Number(id)]);
+    if (!stmt.length) return null;
+    const cols = stmt[0].columns;
+    const v = stmt[0].values[0];
+    const obj = {};
+    cols.forEach((c, i) => obj[c] = v[i]);
+    return obj;
+  }
+
+  async stats(opts = {}) {
+    await this.init();
+    const agent = opts.agent || 'default';
+    const stmt = this._db.exec(
+      `SELECT COUNT(*) as total, MIN(created_at) as oldest, MAX(created_at) as newest, AVG(importance) as avg_importance FROM memories WHERE agent = ?`,
+      [agent]
+    );
+    if (!stmt.length || !stmt[0].values[0][0]) return { total: 0, oldest: null, newest: null, avg_importance: 0 };
+    const [total, oldest, newest, avg_importance] = stmt[0].values[0];
+    return { total, oldest, newest, avg_importance: Math.round(avg_importance * 100) / 100 };
+  }
+
+  async exportAll(opts = {}) {
+    await this.init();
+    const agent = opts.agent;
+    let query = 'SELECT id, text, agent, tags, created_at, importance FROM memories';
+    const params = [];
+    if (agent) {
+      query += ' WHERE agent = ?';
+      params.push(agent);
+    }
+    query += ' ORDER BY id ASC';
+    const stmt = this._db.exec(query, params);
+    if (!stmt.length) return [];
+    const cols = stmt[0].columns;
+    return stmt[0].values.map(v => {
+      const obj = {};
+      cols.forEach((c, i) => obj[c] = v[i]);
+      return obj;
+    });
+  }
+
+  async importAll(memories) {
+    await this.init();
+    let count = 0;
+    for (const m of memories) {
+      this._db.run(
+        'INSERT INTO memories (text, agent, tags, created_at, importance) VALUES (?, ?, ?, ?, ?)',
+        [m.text, m.agent || 'default', m.tags || '', m.created_at || new Date().toISOString(), m.importance || 1.0]
+      );
+      count++;
+    }
+    this._save();
+    return { imported: count };
   }
 }
 
@@ -164,11 +388,21 @@ class ApiClient {
     });
   }
 
-  set(text, opts = {}) { return this._req('POST', '/mem', { text, metadata: opts.metadata }); }
-  recall(query, opts = {}) { return this._req('GET', `/mem/recall?q=${encodeURIComponent(query)}&limit=${opts.limit || 10}`); }
+  async init() {} // no-op for API client
+  set(text, opts = {}) { return this._req('POST', '/mem', { text, tags: opts.tags, importance: opts.importance, metadata: opts.metadata }); }
+  recall(query, opts = {}) {
+    let url = `/mem/recall?q=${encodeURIComponent(query)}&limit=${opts.limit || 10}`;
+    if (opts.tags) url += `&tags=${encodeURIComponent(opts.tags)}`;
+    if (opts.top) url += `&top=${opts.top}`;
+    return this._req('GET', url);
+  }
   list() { return this._req('GET', '/mem/list'); }
   forget(id) { return this._req('DELETE', `/mem/${id}`); }
   clear() { return this._req('DELETE', '/mem?confirm=true'); }
+  important(id) { return this._req('POST', `/mem/${id}/important`); }
+  stats() { return this._req('GET', '/mem/stats'); }
+  exportAll() { return this._req('GET', '/mem/export'); }
+  importAll(memories) { return this._req('POST', '/mem/import', memories); }
 }
 
 // ── Exports ────────────────────────────────────────────────────
@@ -177,18 +411,24 @@ let _store = null;
 
 function getStore() {
   if (!_store) {
-    _store = _config.api ? new ApiClient(_config) : new LocalStore(_config.dir);
+    _store = _config.api
+      ? new ApiClient(_config)
+      : new LocalStore(_config.dir, { openaiKey: _config.openaiKey });
   }
   return _store;
 }
 
 module.exports = {
   configure(opts) { _config = opts; _store = null; },
-  set(text, opts) { return Promise.resolve(getStore().set(text, opts)); },
-  recall(query, opts) { return Promise.resolve(getStore().recall(query, opts)); },
-  list(opts) { return Promise.resolve(getStore().list(opts)); },
-  forget(id) { return Promise.resolve(getStore().forget(id)); },
-  clear(opts) { return Promise.resolve(getStore().clear(opts)); },
+  async set(text, opts) { const s = getStore(); await s.init(); return s.set(text, opts); },
+  async recall(query, opts) { const s = getStore(); await s.init(); return s.recall(query, opts); },
+  async list(opts) { const s = getStore(); await s.init(); return s.list(opts); },
+  async forget(id) { const s = getStore(); await s.init(); return s.forget(id); },
+  async clear(opts) { const s = getStore(); await s.init(); return s.clear(opts); },
+  async important(id, boost) { const s = getStore(); await s.init(); return s.important(id, boost); },
+  async stats(opts) { const s = getStore(); await s.init(); return s.stats(opts); },
+  async exportAll(opts) { const s = getStore(); await s.init(); return s.exportAll(opts); },
+  async importAll(memories) { const s = getStore(); await s.init(); return s.importAll(memories); },
   TfIdf,
   LocalStore,
   ApiClient