mumpix 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mumpix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# Mumpix
+
+**SQLite for AI** — embedded, zero-config memory database for AI agents and LLM applications.
+
+```bash
+npm install mumpix
+```
+
+---
+
+## Why Mumpix?
+
+If you've ever watched an agent "forget" what it just learned, or had to explain why the same prompt produced a different result a day later — Mumpix is your fix.
+
+- **Zero config** — one file, zero external dependencies, works offline
+- **Portable** — the `.mumpix` file is the API. Copy it, move it, back it up
+- **Crash-safe** — WAL-based atomicity: records are either fully written or fully absent
+- **Hybrid recall** — exact match + TF-IDF semantic similarity out of the box
+- **Verified consistency** — immutable audit log, snapshot replay, compliance artifacts
+- **LangChain / LlamaIndex adapters** — drop-in integrations
+
+---
+
+## Quickstart
+
+```js
+const { Mumpix } = require('mumpix')
+
+// Open (or create) a local database
+const db = Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+
+// Store memories
+await db.remember('User prefers TypeScript over JavaScript')
+await db.remember('Project uses pnpm workspaces')
+
+// Semantic recall — no API key, no cloud
+const answer = await db.recall('what language does the user prefer?')
+console.log(answer)
+// → 'User prefers TypeScript over JavaScript'
+
+await db.close()
+```
+
+---
+
+## API
+
+### `Mumpix.open(filePath, [opts])` → `MumpixDB`
+
+Opens (or creates) a Mumpix database.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `consistency` | `string` | `'eventual'` | `'eventual'` / `'strict'` / `'verified'` |
+| `embedFn` | `async fn(texts[]) → number[][]` | — | Custom embedding function (OpenAI, Cohere, etc.) |
+
+### Consistency modes
+
+| Mode | Write behaviour | Audit log | Use case |
+|---|---|---|---|
+| `eventual` | Fast append, OS-buffered | No | Prototypes, local tools |
+| `strict` | Synced to disk (`fdatasync`) | No | Production agents |
+| `verified` | Synced + immutable audit log | Yes | Fintech, healthcare, regulated AI |
+
+---
+
+### Core methods
+
+```js
+// Store a memory
+await db.remember(text)
+// → { written: true, id: 1, consistency: 'strict' }
+
+// Recall the best semantic match
+await db.recall(query)
+// → 'User prefers TypeScript over JavaScript'   or   null
+
+// Recall top-k matches with scores
+await db.recallMany(query, k = 5)
+// → [{ id, content, ts, score }, ...]
+
+// Store multiple memories
+await db.rememberAll(['pref 1', 'pref 2', 'pref 3'])
+
+// Check if any memory matches
+await db.has(query)
+// → true | false
+
+// List all memories
+await db.list()
+// → [{ id, content, ts }, ...]
+
+// Delete all memories
+await db.clear()
+// → { cleared: true, count: 3 }
+
+// Stats
+await db.stats()
+// → { path, consistency, records, sizeBytes, created, version }
+
+// Close (releases file handles)
+await db.close()
+```
+
+### Verified-mode methods
+
+```js
+const db = Mumpix.open('./compliance.mumpix', { consistency: 'verified' })
+
+// Full audit log
+await db.audit()
+// → [{ _type, id, hash, ts, ... }, ...]
+
+// Summary for dashboards
+await db.auditSummary()
+// → { totalEntries, writes, recalls, clears, firstEventAt, lastEventAt, auditPath }
+
+// Export as NDJSON (for compliance hand-off)
+await db.exportAudit()
+// → NDJSON string
+```
+
+### Recall options
+
+```js
+await db.recall(query, {
+  mode:   'hybrid',   // 'hybrid' | 'exact' | 'semantic'
+  filter: r => r.ts > Date.now() - 3600_000,   // only last hour
+  since:  Date.now() - 86400_000,              // shorthand for time filter
+})
+
+await db.recallMany(query, 5, { mode: 'semantic' })
+```
+
+### Custom embeddings (OpenAI, Cohere, etc.)
+
+```js
+const { Mumpix } = require('mumpix')
+const OpenAI = require('openai')
+
+const client = new OpenAI()
+
+async function embedFn(texts) {
+  const res = await client.embeddings.create({ model: 'text-embedding-3-small', input: texts })
+  return res.data.map(d => d.embedding)
+}
+
+const db = Mumpix.open('./agent.mumpix', { consistency: 'strict', embedFn })
+// db.recall() and db.recallMany() now use OpenAI embeddings automatically
+```
+
+---
+
+## LangChain integration
+
+```js
+const { Mumpix } = require('mumpix')
+const { MumpixVectorStore, MumpixChatMemory, MumpixRetriever } = require('mumpix/src/integrations/langchain')
+
+const db = Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+
+// As a VectorStore
+const store = new MumpixVectorStore(db)
+await store.addTexts(['preference 1', 'preference 2'])
+const docs = await store.similaritySearch('query', 4)
+
+// As chat memory (stores Human/AI turns, recalls semantically)
+const memory = new MumpixChatMemory({ db, k: 4 })
+
+// As a retriever
+const retriever = new MumpixRetriever(db, { k: 5 })
+const results = await retriever.getRelevantDocuments('query')
+```
+
+## LlamaIndex integration
+
+```js
+const { Mumpix } = require('mumpix')
+const { MumpixIndex, MumpixReader } = require('mumpix/src/integrations/llamaindex')
+
+const db = Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+
+const index    = new MumpixIndex(db)
+const retriever = index.asRetriever({ topK: 5 })
+
+await index.insert('User prefers dark mode')
+const nodes = await retriever.retrieve('interface preferences')
+
+// Load all memories as documents
+const reader = new MumpixReader(db)
+const docs   = await reader.loadData()
+```
+
+---
+
+## CLI
+
+```bash
+# Global install
+npm install -g mumpix
+
+mumpix remember ./agent.mumpix "User prefers TypeScript"
+mumpix recall   ./agent.mumpix "what language?"
+mumpix search   ./agent.mumpix "language" 3
+mumpix list     ./agent.mumpix
+mumpix clear    ./agent.mumpix
+mumpix stats    ./agent.mumpix
+mumpix audit    ./agent.mumpix    # verified mode only
+mumpix shell    ./agent.mumpix    # interactive REPL
+
+# Options
+mumpix recall ./agent.mumpix "query" --consistency=strict
+mumpix shell  ./compliance.mumpix --consistency=verified
+```
+
+---
+
+## File format
+
+The `.mumpix` file is plain NDJSON — human-readable, portable, no binary parser required:
+
+```
+{"v":1,"consistency":"strict","created":1740000000000,"path":"agent.mumpix"}
+{"id":1,"content":"User prefers TypeScript","ts":1740000001000,"h":"0x4a2b1c3d"}
+{"id":2,"content":"Use pnpm workspaces","ts":1740000002000,"h":"0x9f8e7d6c"}
+```
+
+**Crash safety**: Mumpix uses a WAL (`.mumpix.wal`). On write:
+1. Write to WAL
+2. Append to main file and `fdatasync` (strict/verified)
+3. Delete WAL
+
+On open, any leftover WAL is replayed before accepting new writes. A record is either fully present or fully absent — no partial writes.
+
+**Audit log**: In `verified` mode, an additional `.mumpix.audit` file is created. It is append-only, never modified, and `fdatasync`'d after every entry.
+
+---
+
+## Examples
+
+```bash
+node examples/basic.js          # Zero-config 5-line demo
+node examples/agent-memory.js   # Persistent agent preferences (run twice)
+node examples/verified-mode.js  # Compliance audit log export
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Zero runtime dependencies
+
+---
+
+## License
+
+MIT © Mumpix

package/bin/mumpix.js

@@ -0,0 +1,305 @@
+#!/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 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
+  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
+`.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');
+
+async function main() {
+  const { args, flags } = parseArgs(process.argv.slice(2));
+  const [command, filePath, ...rest] = args;
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  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 = 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);
+});

package/examples/agent-memory.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * examples/agent-memory.js
+ *
+ * Demonstrates Mumpix as persistent memory for an AI agent.
+ * The agent "remembers" across restarts — the .mumpix file persists.
+ *
+ * Run:
+ *   node examples/agent-memory.js
+ *   node examples/agent-memory.js   ← run again; memory persists
+ */
+
+const { Mumpix } = require('../src/index');
+const path = require('path');
+
+const DB_PATH = path.join(__dirname, 'agent-memory.mumpix');
+
+;(async () => {
+  const db = Mumpix.open(DB_PATH, { consistency: 'strict' });
+  const { records } = await db.stats();
+
+  if (records === 0) {
+    console.log('First run — seeding agent preferences...\n');
+
+    await db.rememberAll([
+      'User timezone is America/New_York',
+      'User prefers concise responses, no bullet points',
+      'User is building a B2B SaaS product called "Locaify"',
+      'User always uses TypeScript, never plain JavaScript',
+      'User runs pnpm workspaces',
+      'Preferred output format: JSON when structured, plain prose otherwise',
+    ]);
+
+    console.log(`Seeded ${db.size} preferences.\n`);
+  } else {
+    console.log(`Loaded ${records} existing memories from ${DB_PATH}\n`);
+  }
+
+  // Simulate agent planning queries
+  const queries = [
+    'What is the user\'s timezone?',
+    'How should I format my response?',
+    'What are they building?',
+    'Which package manager?',
+  ];
+
+  console.log('Agent recall test:');
+  for (const q of queries) {
+    const answer = await db.recall(q);
+    console.log(`  Q: ${q}`);
+    console.log(`  A: ${answer ?? '(no match)'}`);
+    console.log();
+  }
+
+  // Top-3 recall
+  console.log('Top-3 for "output format and style":');
+  const top = await db.recallMany('output format and style', 3);
+  top.forEach(r => console.log(`  [${(r.score * 100).toFixed(1)}%] ${r.content}`));
+
+  await db.close();
+  console.log('\nRun this file again — the memories persist.');
+})();

package/examples/basic.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * examples/basic.js — zero-config, 5-line demo
+ *
+ * Run:
+ *   node examples/basic.js
+ */
+
+const { Mumpix } = require('../src/index');
+const os   = require('os');
+const path = require('path');
+
+;(async () => {
+  const dbPath = path.join(os.tmpdir(), 'mumpix-basic-demo.mumpix');
+  const db = Mumpix.open(dbPath, { consistency: 'strict' });
+
+  // Store memories
+  await db.remember('User prefers TypeScript over JavaScript');
+  await db.remember('Always use async/await, never raw Promises');
+  await db.remember('Project uses pnpm, not npm');
+
+  // Semantic recall
+  const lang = await db.recall('What language does the user prefer?');
+  console.log('Recalled:', lang);
+  // → 'User prefers TypeScript over JavaScript'
+
+  const pkgMgr = await db.recall('which package manager?');
+  console.log('Recalled:', pkgMgr);
+  // → 'Project uses pnpm, not npm'
+
+  // List all
+  const all = await db.list();
+  console.log(`\nAll ${all.length} memories:`);
+  all.forEach(m => console.log(`  #${m.id} ${m.content}`));
+
+  // Stats
+  const stats = await db.stats();
+  console.log(`\nDB at ${stats.path} — ${stats.records} records, ${stats.sizeBytes} bytes`);
+
+  await db.close();
+  require('fs').unlinkSync(dbPath);
+  console.log('\nDone.');
+})();