mumpix 1.0.19 → 1.1.3

package/bin/mumpix.js

@@ -1,406 +1,2 @@
 #!/usr/bin/env node
-'use strict';
-
-/**
- * mumpix CLI
- *
- * Usage:
- *   mumpix remember ./agent.mumpix "User prefers TypeScript"
- *   mumpix recall   ./agent.mumpix "what language?"
- *   mumpix list     ./agent.mumpix
- *   mumpix clear    ./agent.mumpix
- *   mumpix stats    ./agent.mumpix
- *   mumpix audit    ./agent.mumpix
- *   mumpix shell    ./agent.mumpix     # interactive REPL
- */
-
-const path   = require('path');
-const readline = require('readline');
-const { Mumpix } = require('../src/index');
-const {
-  loadAuthState,
-  clearAuthState,
-  upsertStoredLicense,
-  exchangeTokenForLicense,
-  loginWithDeviceFlow,
-  authStatePath,
-  configDir,
-} = require('../src/core/auth');
-
-const USAGE = `
-mumpix — SQLite for AI
-
-Usage:
-  mumpix <command> <file> [args...]
-
-Commands:
-  remember <file> "<text>"         Store a memory
-  recall   <file> "<query>"        Recall the best match
-  search   <file> "<query>" [k]    Recall top-k matches
-  list     <file>                  List all memories
-  clear    <file>                  Clear all memories
-  stats    <file>                  Show database stats
-  audit    <file>                  Show audit log (verified mode)
-  shell    <file>                  Start interactive REPL
-  auth     <subcommand>            Account login/logout/status
-  help                             Show this message
-
-Options (append to any command):
-  --consistency=eventual|strict|verified   (default: eventual)
-
-Examples:
-  mumpix remember ./agent.mumpix "User prefers TypeScript"
-  mumpix recall   ./agent.mumpix "what language?" --consistency=strict
-  mumpix search   ./agent.mumpix "TypeScript" 3
-  mumpix shell    ./agent.mumpix --consistency=verified
-  mumpix auth status
-  mumpix auth login --token=<account-token>
-  mumpix auth login --license=<signed-license-key>
-`.trim();
-
-function parseArgs(argv) {
-  const args    = [];
-  const flags   = {};
-  for (const arg of argv) {
-    if (arg.startsWith('--')) {
-      const [k, v] = arg.slice(2).split('=');
-      flags[k] = v !== undefined ? v : true;
-    } else {
-      args.push(arg);
-    }
-  }
-  return { args, flags };
-}
-
-function fmt(val) {
-  if (val === null)  return 'null';
-  if (typeof val === 'string') return val;
-  return JSON.stringify(val, null, 2);
-}
-
-function colorize(text, code) {
-  if (!process.stdout.isTTY) return text;
-  return `\x1b[${code}m${text}\x1b[0m`;
-}
-
-const dim    = t => colorize(t, '2');
-const cyan   = t => colorize(t, '36');
-const green  = t => colorize(t, '32');
-const yellow = t => colorize(t, '33');
-const red    = t => colorize(t, '31');
-const bold   = t => colorize(t, '1');
-
-function fmtExpiry(ts) {
-  if (!ts) return '-';
-  const d = new Date(Number(ts));
-  if (Number.isNaN(d.getTime())) return '-';
-  return d.toISOString();
-}
-
-function mask(value, keep = 6) {
-  const s = String(value || '');
-  if (s.length <= keep) return s;
-  return `${s.slice(0, keep)}…`;
-}
-
-async function runAuth(parts, flags) {
-  const sub = String(parts[0] || 'status').toLowerCase();
-
-  if (sub === 'status') {
-    const s = loadAuthState();
-    if (!s || !s.license || !s.license.key) {
-      console.log(dim('Not logged in.'));
-      console.log(dim(`Config dir: ${configDir()}`));
-      return;
-    }
-    console.log(bold('Mumpix auth status'));
-    console.log(`  account_id: ${s.account && s.account.id ? s.account.id : '-'}`);
-    console.log(`  tier:       ${s.license.tier || (s.account && s.account.tier) || '-'}`);
-    console.log(`  issued_at:  ${fmtExpiry(s.license.iat)}`);
-    console.log(`  expires_at: ${fmtExpiry(s.license.exp)}`);
-    console.log(`  license:    ${green(mask(s.license.key, 18))}`);
-    console.log(`  state:      ${authStatePath()}`);
-    return;
-  }
-
-  if (sub === 'logout') {
-    clearAuthState();
-    console.log(green('✓') + ' Logged out. Local license removed.');
-    return;
-  }
-
-  if (sub === 'login') {
-    const directLicense = flags.license || flags['license-key'] || null;
-    if (directLicense) {
-      const state = upsertStoredLicense(String(directLicense));
-      console.log(green('✓') + ' License saved.');
-      console.log(`  tier:       ${state.license.tier || '-'}`);
-      console.log(`  expires_at: ${fmtExpiry(state.license.exp)}`);
-      console.log(`  state:      ${authStatePath()}`);
-      return;
-    }
-
-    const token = flags.token || process.env.MUMPIX_AUTH_TOKEN || '';
-    if (token) {
-      const state = await exchangeTokenForLicense(String(token).trim(), {});
-      console.log(green('✓') + ' Account linked and license saved.');
-      console.log(`  account_id: ${state.account.id || '-'}`);
-      console.log(`  tier:       ${state.license.tier || state.account.tier || '-'}`);
-      console.log(`  expires_at: ${fmtExpiry(state.license.exp)}`);
-      console.log(`  state:      ${authStatePath()}`);
-      return;
-    }
-
-    const state = await loginWithDeviceFlow({
-      onPrompt: ({ userCode, verifyUrl, expiresInSec, intervalSec }) => {
-        console.log(bold('Mumpix device login'));
-        console.log(`  1) Open: ${verifyUrl}`);
-        console.log(`  2) Enter code: ${cyan(userCode)}`);
-        console.log(`  3) Waiting for approval... (expires in ${expiresInSec}s, polling ${intervalSec}s)`);
-      }
-    });
-    console.log(green('✓') + ' Account linked and license saved.');
-    console.log(`  account_id: ${state.account.id || '-'}`);
-    console.log(`  tier:       ${state.license.tier || state.account.tier || '-'}`);
-    console.log(`  expires_at: ${fmtExpiry(state.license.exp)}`);
-    console.log(`  state:      ${authStatePath()}`);
-    return;
-  }
-
-  console.error(red(`Unknown auth subcommand: ${sub}`));
-  console.log('Usage: mumpix auth <status|login|logout> [--token=...] [--license=...]');
-  process.exit(1);
-}
-
-async function main() {
-  const { args, flags } = parseArgs(process.argv.slice(2));
-  const [command, arg1, ...rest] = args;
-
-  if (!command || command === 'help' || command === '--help' || command === '-h') {
-    console.log(USAGE);
-    process.exit(0);
-  }
-
-  if (command === 'auth') {
-    await runAuth([arg1, ...rest], flags);
-    return;
-  }
-
-  const filePath = arg1;
-  if (!filePath && command !== 'help') {
-    console.error(red('Error: file path required'));
-    console.log(USAGE);
-    process.exit(1);
-  }
-
-  const consistency = flags.consistency || 'eventual';
-  let db;
-
-  try {
-    db = await Mumpix.open(filePath, { consistency });
-  } catch (err) {
-    console.error(red(`Error opening ${filePath}: ${err.message}`));
-    process.exit(1);
-  }
-
-  try {
-    switch (command) {
-
-      case 'remember': {
-        const text = rest.join(' ').replace(/^["']|["']$/g, '');
-        if (!text) { console.error(red('Error: provide text to remember')); process.exit(1); }
-        const result = await db.remember(text);
-        console.log(green('✓') + ` Stored as #${result.id} (${result.consistency})`);
-        break;
-      }
-
-      case 'recall': {
-        const query = rest.join(' ').replace(/^["']|["']$/g, '');
-        if (!query) { console.error(red('Error: provide a query')); process.exit(1); }
-        const result = await db.recall(query);
-        if (result === null) {
-          console.log(dim('No memories found.'));
-        } else {
-          console.log(green('→') + ' ' + result);
-        }
-        break;
-      }
-
-      case 'search': {
-        const k     = parseInt(rest[rest.length - 1], 10);
-        const limit = Number.isInteger(k) && k > 0 ? k : 5;
-        const queryParts = Number.isInteger(k) ? rest.slice(0, -1) : rest;
-        const query = queryParts.join(' ').replace(/^["']|["']$/g, '');
-        if (!query) { console.error(red('Error: provide a query')); process.exit(1); }
-        const results = await db.recallMany(query, limit);
-        if (!results.length) {
-          console.log(dim('No memories found.'));
-        } else {
-          results.forEach((r, i) => {
-            const score = r.score !== undefined ? dim(` (${(r.score * 100).toFixed(1)}%)`) : '';
-            console.log(`${cyan(`#${r.id}`)} ${r.content}${score}`);
-          });
-        }
-        break;
-      }
-
-      case 'list': {
-        const memories = await db.list();
-        if (!memories.length) {
-          console.log(dim('No memories stored.'));
-        } else {
-          memories.forEach(m => {
-            const ts = new Date(m.ts).toLocaleString();
-            console.log(`${cyan(`#${m.id}`)} ${m.content} ${dim(ts)}`);
-          });
-          console.log(dim(`\n${memories.length} total`));
-        }
-        break;
-      }
-
-      case 'clear': {
-        const { count } = await db.clear();
-        console.log(yellow('⚠') + ` Cleared ${count} ${count === 1 ? 'memory' : 'memories'}`);
-        break;
-      }
-
-      case 'stats': {
-        const s = await db.stats();
-        console.log(bold('Mumpix stats'));
-        console.log(`  path:        ${s.path}`);
-        console.log(`  consistency: ${cyan(s.consistency)}`);
-        console.log(`  records:     ${s.records}`);
-        console.log(`  size:        ${(s.sizeBytes / 1024).toFixed(2)} KB`);
-        console.log(`  created:     ${new Date(s.created).toLocaleString()}`);
-        console.log(`  version:     v${s.version}`);
-        break;
-      }
-
-      case 'audit': {
-        let entries;
-        try {
-          entries = await db.audit();
-        } catch (err) {
-          console.error(red('Error: ') + err.message);
-          process.exit(1);
-        }
-        if (!entries.length) {
-          console.log(dim('Audit log is empty.'));
-        } else {
-          entries.forEach(e => {
-            const ts = new Date(e.ts).toISOString();
-            const type = e._type.padEnd(12);
-            const detail = e._type === 'write'  ? `id=${e.id} hash=${e.hash}`
-                         : e._type === 'recall' ? `queryHash=${e.queryHash} resultId=${e.resultId ?? 'null'} latency=${e.latencyMs}ms`
-                         : e._type === 'clear'  ? `count=${e.count}`
-                         : '';
-            console.log(`${dim(ts)} ${yellow(type)} ${detail}`);
-          });
-          console.log(dim(`\n${entries.length} entries`));
-        }
-        break;
-      }
-
-      case 'shell': {
-        await runShell(db, filePath, consistency);
-        break;
-      }
-
-      default:
-        console.error(red(`Unknown command: ${command}`));
-        console.log(USAGE);
-        process.exit(1);
-    }
-  } finally {
-    if (command !== 'shell') await db.close();
-  }
-}
-
-async function runShell(db, filePath, consistency) {
-  const rl = readline.createInterface({
-    input:  process.stdin,
-    output: process.stdout,
-    prompt: cyan('mumpix') + dim(' › '),
-    historySize: 100,
-  });
-
-  console.log(bold('Mumpix interactive shell'));
-  console.log(dim(`  file: ${filePath}  consistency: ${consistency}`));
-  console.log(dim('  Commands: remember("…"), recall("…"), list(), clear(), stats(), audit(), exit\n'));
-
-  rl.prompt();
-
-  rl.on('line', async (line) => {
-    const raw = line.trim();
-    if (!raw) { rl.prompt(); return; }
-    if (raw === 'exit' || raw === 'quit' || raw === '.exit') {
-      console.log(dim('bye'));
-      rl.close();
-      await db.close();
-      process.exit(0);
-    }
-
-    const match = raw.match(/^(\w+)\s*\((.*)?\)$/s);
-    if (!match) {
-      console.log(red('Syntax error') + dim(' — try: remember("…") or recall("…")'));
-      rl.prompt();
-      return;
-    }
-
-    const [, fn, argsRaw] = match;
-    const strArg = (s => {
-      const m = (s || '').trim().match(/^["'`]([\s\S]*)["'`]$/);
-      return m ? m[1] : null;
-    })(argsRaw);
-
-    try {
-      let result;
-      switch (fn) {
-        case 'remember':
-          if (strArg === null) throw new Error('remember() expects a string');
-          result = await db.remember(strArg);
-          console.log(green('←') + ' ' + JSON.stringify(result));
-          break;
-        case 'recall':
-          if (strArg === null) throw new Error('recall() expects a string');
-          result = await db.recall(strArg);
-          console.log(green('←') + ' ' + (result === null ? dim('null') : JSON.stringify(result)));
-          break;
-        case 'list':
-          result = await db.list();
-          if (!result.length) console.log(dim('[]'));
-          else result.forEach(m => console.log(`  ${cyan(`#${m.id}`)} ${m.content}`));
-          break;
-        case 'clear':
-          result = await db.clear();
-          console.log(green('←') + ' ' + JSON.stringify(result));
-          break;
-        case 'stats':
-          result = await db.stats();
-          console.log(green('←') + ' ' + JSON.stringify(result, null, 2));
-          break;
-        case 'audit':
-          result = await db.audit();
-          if (!result.length) console.log(dim('[]'));
-          else result.forEach(e => console.log('  ' + JSON.stringify(e)));
-          break;
-        default:
-          console.log(red(`Unknown: db.${fn}`));
-      }
-    } catch (err) {
-      console.log(red('Error: ') + err.message);
-    }
-
-    rl.prompt();
-  });
-
-  rl.on('close', async () => {
-    await db.close();
-    process.exit(0);
-  });
-}
-
-main().catch(err => {
-  console.error(err.message);
-  process.exit(1);
-});
+"use strict";require("path");const e=require("readline"),{Mumpix:o}=require("../src/index"),{loadAuthState:t,clearAuthState:n,upsertStoredLicense:s,exchangeTokenForLicense:c,loginWithDeviceFlow:l,authStatePath:r,configDir:i}=require("../src/core/auth"),{LicenseManager:a}=require("../src/core/license"),g='\nmumpix \u2014 SQLite for AI\n\nUsage:\n  mumpix <command> <file> [args...]\n\nCommands:\n  remember <file> "<text>"         Store a memory\n  recall   <file> "<query>"        Recall the best match\n  search   <file> "<query>" [k]    Recall top-k matches\n  list     <file>                  List all memories\n  clear    <file>                  Clear all memories\n  stats    <file>                  Show database stats\n  audit    <file>                  Show audit log (verified mode)\n  shell    <file>                  Start interactive REPL\n  auth     <subcommand>            Account login/logout/status\n  help                             Show this message\n\nOptions (append to any command):\n  --consistency=eventual|strict|verified   (default: eventual)\n\nExamples:\n  mumpix remember ./agent.mumpix "User prefers TypeScript"\n  mumpix recall   ./agent.mumpix "what language?" --consistency=strict\n  mumpix search   ./agent.mumpix "TypeScript" 3\n  mumpix shell    ./agent.mumpix --consistency=verified\n  mumpix auth status\n  mumpix auth device-id\n  mumpix auth login --token=<account-token>\n  mumpix auth login --license=<signed-license-key>\n'.trim();function u(e,o){return process.stdout.isTTY?`\x1b[${o}m${e}\x1b[0m`:e}const m=e=>u(e,"2"),p=e=>u(e,"36"),d=e=>u(e,"32"),h=e=>u(e,"33"),$=e=>u(e,"31"),f=e=>u(e,"1");function y(e){if(!e)return"-";const o=new Date(Number(e));return Number.isNaN(o.getTime())?"-":o.toISOString()}async function x(e,o){const g=String(e[0]||"status").toLowerCase();if("status"===g){const e=t();return e&&e.license&&e.license.key?(console.log(f("Mumpix auth status")),console.log(`  account_id: ${e.account&&e.account.id?e.account.id:"-"}`),console.log(`  tier:       ${e.license.tier||e.account&&e.account.tier||"-"}`),console.log(`  issued_at:  ${y(e.license.iat)}`),console.log(`  expires_at: ${y(e.license.exp)}`),console.log(`  license:    ${d(function(e,o=6){const t=String(e||"");return t.length<=o?t:`${t.slice(0,o)}\u2026`}(e.license.key,18))}`),void console.log(`  state:      ${r()}`)):(console.log(m("Not logged in.")),void console.log(m(`Config dir: ${i()}`)))}if("logout"===g)return n(),void console.log(d("\u2713")+" Logged out. Local license removed.");if("device-id"===g||"device"===g||"fingerprint"===g){const e=new a,o=await e.deviceIdentityInfo();return console.log(f("Mumpix device identity")),console.log(`  algorithm:   ${o.algorithm}`),console.log(`  fingerprint: ${d(o.publicKeyFingerprint)}`),console.log(`  public_key:  ${o.publicKeyB64}`),void console.log(`  state:       ${o.path}`)}if("login"===g){const e=o.license||o["license-key"]||null;if(e){const o=s(String(e));return console.log(d("\u2713")+" License saved."),console.log(`  tier:       ${o.license.tier||"-"}`),console.log(`  expires_at: ${y(o.license.exp)}`),void console.log(`  state:      ${r()}`)}const t=o.token||process.env.MUMPIX_AUTH_TOKEN||"";if(t){const e=await c(String(t).trim(),{});return console.log(d("\u2713")+" Account linked and license saved."),console.log(`  account_id: ${e.account.id||"-"}`),console.log(`  tier:       ${e.license.tier||e.account.tier||"-"}`),console.log(`  expires_at: ${y(e.license.exp)}`),void console.log(`  state:      ${r()}`)}const n=await l({onPrompt:({userCode:e,verifyUrl:o,expiresInSec:t,intervalSec:n})=>{console.log(f("Mumpix device login")),console.log(`  1) Open: ${o}`),console.log(`  2) Enter code: ${p(e)}`),console.log(`  3) Waiting for approval... (expires in ${t}s, polling ${n}s)`)}});return console.log(d("\u2713")+" Account linked and license saved."),console.log(`  account_id: ${n.account.id||"-"}`),console.log(`  tier:       ${n.license.tier||n.account.tier||"-"}`),console.log(`  expires_at: ${y(n.license.exp)}`),void console.log(`  state:      ${r()}`)}console.error($(`Unknown auth subcommand: ${g}`)),console.log("Usage: mumpix auth <status|login|logout|device-id> [--token=...] [--license=...]"),process.exit(1)}(async function(){const{args:t,flags:n}=function(e){const o=[],t={};for(const n of e)if(n.startsWith("--")){const[e,o]=n.slice(2).split("=");t[e]=void 0===o||o}else o.push(n);return{args:o,flags:t}}(process.argv.slice(2)),[s,c,...l]=t;if(s&&"help"!==s&&"--help"!==s&&"-h"!==s||(console.log(g),process.exit(0)),"auth"===s)return void await x([c,...l],n);const r=c;r||"help"===s||(console.error($("Error: file path required")),console.log(g),process.exit(1));const i=n.consistency||"eventual";let a;try{a=await o.open(r,{consistency:i})}catch(e){console.error($(`Error opening ${r}: ${e.message}`)),process.exit(1)}try{switch(s){case"remember":{const e=l.join(" ").replace(/^["']|["']$/g,"");e||(console.error($("Error: provide text to remember")),process.exit(1));const o=await a.remember(e);console.log(d("\u2713")+` Stored as #${o.id} (${o.consistency})`);break}case"recall":{const e=l.join(" ").replace(/^["']|["']$/g,"");e||(console.error($("Error: provide a query")),process.exit(1));const o=await a.recall(e);null===o?console.log(m("No memories found.")):console.log(d("\u2192")+" "+o);break}case"search":{const e=parseInt(l[l.length-1],10),o=Number.isInteger(e)&&e>0?e:5,t=(Number.isInteger(e)?l.slice(0,-1):l).join(" ").replace(/^["']|["']$/g,"");t||(console.error($("Error: provide a query")),process.exit(1));const n=await a.recallMany(t,o);n.length?n.forEach((e,o)=>{const t=void 0!==e.score?m(` (${(100*e.score).toFixed(1)}%)`):"";console.log(`${p(`#${e.id}`)} ${e.content}${t}`)}):console.log(m("No memories found."));break}case"list":{const e=await a.list();e.length?(e.forEach(e=>{const o=new Date(e.ts).toLocaleString();console.log(`${p(`#${e.id}`)} ${e.content} ${m(o)}`)}),console.log(m(`\n${e.length} total`))):console.log(m("No memories stored."));break}case"clear":{const{count:e}=await a.clear();console.log(h("\u26a0")+` Cleared ${e} ${1===e?"memory":"memories"}`);break}case"stats":{const e=await a.stats();console.log(f("Mumpix stats")),console.log(`  path:        ${e.path}`),console.log(`  consistency: ${p(e.consistency)}`),console.log(`  records:     ${e.records}`),console.log(`  size:        ${(e.sizeBytes/1024).toFixed(2)} KB`),console.log(`  created:     ${new Date(e.created).toLocaleString()}`),console.log(`  version:     v${e.version}`);break}case"audit":{let e;try{e=await a.audit()}catch(e){console.error($("Error: ")+e.message),process.exit(1)}e.length?(e.forEach(e=>{const o=new Date(e.ts).toISOString(),t=e._type.padEnd(12),n="write"===e._type?`id=${e.id} hash=${e.hash}`:"recall"===e._type?`queryHash=${e.queryHash} resultId=${e.resultId??"null"} latency=${e.latencyMs}ms`:"clear"===e._type?`count=${e.count}`:"";console.log(`${m(o)} ${h(t)} ${n}`)}),console.log(m(`\n${e.length} entries`))):console.log(m("Audit log is empty."));break}case"shell":await async function(o,t,n){const s=e.createInterface({input:process.stdin,output:process.stdout,prompt:p("mumpix")+m(" \u203a "),historySize:100});console.log(f("Mumpix interactive shell")),console.log(m(`  file: ${t}  consistency: ${n}`)),console.log(m('  Commands: remember("\u2026"), recall("\u2026"), list(), clear(), stats(), audit(), exit\n')),s.prompt(),s.on("line",async e=>{const t=e.trim();if(!t)return void s.prompt();"exit"!==t&&"quit"!==t&&".exit"!==t||(console.log(m("bye")),s.close(),await o.close(),process.exit(0));const n=t.match(/^(\w+)\s*\((.*)?\)$/s);if(!n)return console.log($("Syntax error")+m(' \u2014 try: remember("\u2026") or recall("\u2026")')),void s.prompt();const[,c,l]=n,r=(e=>{const o=(e||"").trim().match(/^["'`]([\s\S]*)["'`]$/);return o?o[1]:null})(l);try{let e;switch(c){case"remember":if(null===r)throw new Error("remember() expects a string");e=await o.remember(r),console.log(d("\u2190")+" "+JSON.stringify(e));break;case"recall":if(null===r)throw new Error("recall() expects a string");e=await o.recall(r),console.log(d("\u2190")+" "+(null===e?m("null"):JSON.stringify(e)));break;case"list":e=await o.list(),e.length?e.forEach(e=>console.log(`  ${p(`#${e.id}`)} ${e.content}`)):console.log(m("[]"));break;case"clear":e=await o.clear(),console.log(d("\u2190")+" "+JSON.stringify(e));break;case"stats":e=await o.stats(),console.log(d("\u2190")+" "+JSON.stringify(e,null,2));break;case"audit":e=await o.audit(),e.length?e.forEach(e=>console.log("  "+JSON.stringify(e))):console.log(m("[]"));break;default:console.log($(`Unknown: db.${c}`))}}catch(e){console.log($("Error: ")+e.message)}s.prompt()}),s.on("close",async()=>{await o.close(),process.exit(0)})}(a,r,i);break;default:console.error($(`Unknown command: ${s}`)),console.log(g),process.exit(1)}}finally{"shell"!==s&&await a.close()}})().catch(e=>{console.error(e.message),process.exit(1)});

package/examples/agent-memory.js

@@ -17,7 +17,7 @@ const path = require('path');
 const DB_PATH = path.join(__dirname, 'agent-memory.mumpix');
 
 ;(async () => {
-  const db = Mumpix.open(DB_PATH, { consistency: 'strict' });
+  const db = await Mumpix.open(DB_PATH, { consistency: 'eventual' });
   const { records } = await db.stats();
 
   if (records === 0) {

package/examples/basic.js

@@ -13,7 +13,7 @@ const path = require('path');
 
 ;(async () => {
   const dbPath = path.join(os.tmpdir(), 'mumpix-basic-demo.mumpix');
-  const db = Mumpix.open(dbPath, { consistency: 'strict' });
+  const db = await Mumpix.open(dbPath, { consistency: 'eventual' });
 
   // Store memories
   await db.remember('User prefers TypeScript over JavaScript');

package/examples/behavioral-primitives.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { brp, rlp, collapse } = require('../src');
+
+const gene = brp.normalizeBRP({
+  domain: 'browser',
+  trigger_signature: 'login page asks for workspace slug',
+  executable_payload: {
+    intent: 'DO',
+    sequence: [
+      { verb: 'input-text', args: { selector: '#workspace', value: 'acme' } },
+      { verb: 'click-element', args: { selector: 'button[type=submit]' } },
+    ],
+  },
+});
+
+const updated = brp.updateSplitConfidence(gene, {
+  triggerMatched: true,
+  sequenceExecuted: true,
+  breakEvenThreshold: 3,
+});
+
+const match = brp.twoStageMatch([updated], {
+  domain: 'browser',
+  text: 'workspace login form',
+  payload_type: 'DO',
+});
+
+const actionBoundary = rlp.validateActionBoundary(updated);
+
+const economics = collapse.analyzeCollapse({
+  stages: [
+    { name: 'INDEX', token_cost: 200 },
+    { name: 'SCAN', token_cost: 2400 },
+    { name: 'DEBATE', token_cost: 7200 },
+    { name: 'EXECUTE', token_cost: 2050 },
+  ],
+  retrievalCost: 150,
+  promotionCost: 35550,
+  hits: 3,
+});
+
+console.log({
+  brp_id: updated.brp_id,
+  payload_type: updated.payload_type,
+  action_ok: actionBoundary.ok,
+  top_match: match[0] && match[0].brp.brp_id,
+  savings_per_hit: economics.savingsPerHit,
+  break_even_crossed: economics.breakEvenCrossed,
+});

package/examples/recall-quality-suite.js

@@ -0,0 +1,156 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { Mumpix } = require("../src/index");
+
+const DEFAULT_BASE_URL = "http://127.0.0.1:11434/v1";
+const DEFAULT_MODEL = "nomic-embed-text";
+
+class OpenAIEmbeddingEmbedder {
+  constructor({ baseUrl, model, apiKey, dim }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.model = model;
+    this.apiKey = apiKey;
+    this.dim = dim;
+    this.id = `openai-compatible:${this.model}:dim${this.dim}`;
+  }
+
+  static async create() {
+    const baseUrl = process.env.MUMPIX_EMBED_BASE_URL || DEFAULT_BASE_URL;
+    const model = process.env.MUMPIX_EMBED_MODEL || DEFAULT_MODEL;
+    const apiKey = process.env.MUMPIX_EMBED_API_KEY || process.env.OPENAI_API_KEY || "";
+    const probe = new OpenAIEmbeddingEmbedder({ baseUrl, model, apiKey, dim: 1 });
+    const [vector] = await probe.embed(["dimension probe"]);
+    return new OpenAIEmbeddingEmbedder({
+      baseUrl,
+      model,
+      apiKey,
+      dim: vector.length,
+    });
+  }
+
+  async embed(texts) {
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}),
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: texts,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(
+        `Embedding request failed (${response.status}) for ${this.baseUrl}/embeddings model ${this.model}: ${body}`
+      );
+    }
+
+    const json = await response.json();
+    if (!json || !Array.isArray(json.data) || json.data.length !== texts.length) {
+      throw new Error("Embedding response did not include one vector per input.");
+    }
+
+    return json.data
+      .sort((left, right) => left.index - right.index)
+      .map((item) => normalize(item.embedding));
+  }
+}
+
+function normalize(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error("Embedding response included an invalid vector.");
+  }
+  const vector = Float32Array.from(values, Number);
+  const norm = Math.hypot(...vector);
+  if (!Number.isFinite(norm) || norm === 0) {
+    throw new Error("Embedding response included a zero or non-finite vector.");
+  }
+  for (let i = 0; i < vector.length; i += 1) vector[i] /= norm;
+  return vector;
+}
+
+const MEMORIES = [
+  "websocket upgrade requests bypass express middleware auth",
+  "the promotion gate blocked because the human review was missing",
+  "duration getters returned undefined for units absent from the input object",
+  "the stale lock file was removed and the store reopened after SIGKILL",
+  "route selection injected irrelevant genes and degraded a passing fix",
+];
+
+const PARAPHRASES = [
+  "realtime socket connections skip the login check",
+  "promotion halted, approval signoff absent",
+  "timespan accessor gives null for fields not provided",
+  "store recovery after the process was killed",
+  "memory retrieval added noise that broke working code",
+];
+
+function clean(filePath) {
+  for (const suffix of ["", ".wal", ".lock", ".idx", ".vectors.json", ".vectors.jsonl"]) {
+    fs.rmSync(`${filePath}${suffix}`, { force: true, recursive: true });
+  }
+}
+
+(async () => {
+  const embedder = await OpenAIEmbeddingEmbedder.create();
+  const semanticFloor = Number(process.env.MUMPIX_SEMANTIC_FLOOR || 0.5);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mumpix-recall-quality-"));
+  const beforePath = path.join(dir, "before.mumpix");
+  const afterPath = path.join(dir, "after.mumpix");
+  clean(beforePath);
+  clean(afterPath);
+
+  console.log(`embedder: ${embedder.id}`);
+  console.log(`transport: ${embedder.baseUrl}`);
+  console.log(`semanticFloor: ${semanticFloor}`);
+
+  const before = await Mumpix.open(beforePath);
+  const after = await Mumpix.open(afterPath, {
+    recall: "semantic",
+    embedder,
+    semanticFloor,
+  });
+
+  try {
+    for (const memory of MEMORIES) {
+      await before.remember(memory);
+      await after.remember(memory);
+    }
+
+    let beforeHits = 0;
+    let afterHits = 0;
+    for (let i = 0; i < PARAPHRASES.length; i += 1) {
+      const query = PARAPHRASES[i];
+      const lexical = await before.recall(query);
+      const semantic = await after.recall(query);
+      const semanticOk = semantic === MEMORIES[i];
+      if (lexical) beforeHits += 1;
+      if (semanticOk) afterHits += 1;
+      console.log(`Q${i + 1}: ${query}`);
+      console.log(`  before: ${lexical ? "HIT" : "null"}`);
+      console.log(`  after:  ${semanticOk ? "HIT" : semantic ? `WRONG: ${semantic}` : "null"}`);
+    }
+
+    const control = await after.recall("purple elephant tax return kazoo");
+    console.log(`control: ${control === null ? "null" : `FIRED: ${control}`}`);
+    console.log(`before: ${beforeHits}/5`);
+    console.log(`after: ${afterHits}/5`);
+  } finally {
+    await before.close();
+    await after.close();
+    fs.rmSync(dir, { force: true, recursive: true });
+  }
+})().catch((err) => {
+  console.error(err && err.stack ? err.stack : err);
+  console.error("");
+  console.error("This recall quality suite requires a real OpenAI-compatible embedding endpoint.");
+  console.error(`Default local setup: ollama pull ${DEFAULT_MODEL}`);
+  console.error(`Then run: MUMPIX_EMBED_BASE_URL=${DEFAULT_BASE_URL} MUMPIX_EMBED_MODEL=${DEFAULT_MODEL} npm run bench:recall`);
+  process.exit(1);
+});

package/examples/verified-mode.js

@@ -27,7 +27,7 @@ const DB_PATH = path.join(os.tmpdir(), 'mumpix-verified-demo.mumpix');
   });
 
   console.log('Opening Mumpix in Verified mode...\n');
-  const db = Mumpix.open(DB_PATH, { consistency: 'verified' });
+  const db = await Mumpix.open(DB_PATH, { consistency: 'verified' });
 
   // Simulate a compliance-relevant workflow
   await db.remember('Loan application #4821 approved — credit score: 742');