mumpix 1.0.0

package/examples/verified-mode.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * examples/verified-mode.js
+ *
+ * Demonstrates Mumpix's "Verified" consistency mode:
+ *   - Immutable audit log (.mumpix.audit)
+ *   - Every write and recall is logged with hashes
+ *   - Reproducible recall behavior
+ *   - Export audit log as NDJSON for compliance hand-off
+ *
+ * Run:
+ *   node examples/verified-mode.js
+ */
+
+const { Mumpix } = require('../src/index');
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+
+const DB_PATH = path.join(os.tmpdir(), 'mumpix-verified-demo.mumpix');
+
+;(async () => {
+  // Clean up any previous run
+  [DB_PATH, DB_PATH + '.audit', DB_PATH + '.wal'].forEach(f => {
+    if (fs.existsSync(f)) fs.unlinkSync(f);
+  });
+
+  console.log('Opening Mumpix in Verified mode...\n');
+  const db = Mumpix.open(DB_PATH, { consistency: 'verified' });
+
+  // Simulate a compliance-relevant workflow
+  await db.remember('Loan application #4821 approved — credit score: 742');
+  await db.remember('Manual override applied by risk-officer-07 on 2025-02-18');
+  await db.remember('Model version: risk-v3.2.1, threshold: 0.72');
+  await db.remember('Basel III compliance flag: ACTIVE');
+  await db.remember('Customer consent recorded: 2025-02-17T14:32:00Z');
+
+  console.log(`Stored ${db.size} records.\n`);
+
+  // Recall queries
+  const queries = [
+    'Was there a manual override?',
+    'What model was used?',
+    'Is it Basel III compliant?',
+  ];
+
+  console.log('Recall queries:');
+  for (const q of queries) {
+    const ans = await db.recall(q);
+    console.log(`  Q: ${q}`);
+    console.log(`  A: ${ans ?? '(no match)'}`);
+    console.log();
+  }
+
+  // Audit log
+  const entries = await db.audit();
+  console.log(`Audit log (${entries.length} entries):`);
+  entries.forEach(e => {
+    const ts   = new Date(e.ts).toISOString();
+    const type = e._type.padEnd(10);
+    const detail =
+      e._type === 'write'  ? `id=${e.id} hash=${e.hash} len=${e.len}`
+    : e._type === 'recall' ? `queryHash=${e.queryHash} resultId=${e.resultId ?? 'null'} ${e.latencyMs}ms`
+    :                        '';
+    console.log(`  [${ts}] ${type} ${detail}`);
+  });
+
+  // Audit summary
+  const summary = await db.auditSummary();
+  console.log('\nAudit summary:', JSON.stringify(summary, null, 2));
+
+  // Export
+  const ndjson = await db.exportAudit();
+  const exportPath = DB_PATH.replace('.mumpix', '-audit-export.ndjson');
+  fs.writeFileSync(exportPath, ndjson, 'utf8');
+  console.log(`\nAudit exported to: ${exportPath}`);
+
+  await db.close();
+
+  // Cleanup
+  [DB_PATH, DB_PATH + '.audit', exportPath].forEach(f => {
+    if (fs.existsSync(f)) fs.unlinkSync(f);
+  });
+})();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "mumpix",
+  "version": "1.0.0",
+  "description": "SQLite for AI — embedded, zero-config memory database for AI agents and LLM applications",
+  "main": "src/index.js",
+  "bin": {
+    "mumpix": "./bin/mumpix.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "database",
+    "embedded",
+    "vector",
+    "semantic",
+    "llm",
+    "agent",
+    "langchain",
+    "local-first",
+    "sqlite",
+    "storage",
+    "retrieval",
+    "rag"
+  ],
+  "author": "Mumpix",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "files": [
+    "src/",
+    "bin/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mumpix/mumpix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mumpix/mumpix/issues"
+  },
+  "homepage": "https://mumpix.dev"
+}

package/src/core/MumpixDB.js

@@ -0,0 +1,306 @@
+'use strict';
+
+/**
+ * MumpixDB — main database class
+ *
+ * const { Mumpix } = require('mumpix')
+ * const db = await Mumpix.open('./agent.mumpix', { consistency: 'strict' })
+ *
+ * await db.remember('User prefers TypeScript')
+ * const ans = await db.recall('what language?')
+ * const all = await db.list()
+ * await db.clear()
+ * await db.close()
+ */
+
+const { MumpixStore } = require('./store');
+const { MumpixAudit } = require('./audit');
+const { recall, recallMany } = require('./recall');
+
+const VALID_MODES = ['eventual', 'strict', 'verified'];
+
+class MumpixDB {
+  /**
+   * @param {MumpixStore} store
+   * @param {MumpixAudit|null} audit
+   * @param {object} opts
+   */
+  constructor(store, audit, opts = {}) {
+    this._store   = store;
+    this._audit   = audit;   // non-null only in 'verified' mode
+    this._opts    = opts;
+    this._closed  = false;
+  }
+
+  // ─────────────────────────────────────────
+  // Factory
+  // ─────────────────────────────────────────
+
+  /**
+   * Open (or create) a Mumpix database.
+   *
+   * @param {string} filePath  Path to .mumpix file
+   * @param {object} [opts]
+   * @param {string} [opts.consistency]  'eventual' | 'strict' | 'verified' (default: 'eventual')
+   * @param {Function} [opts.embedFn]    async (texts: string[]) => number[][] — optional custom embeddings
+   * @returns {MumpixDB}
+   */
+  static open(filePath, opts = {}) {
+    if (!filePath || typeof filePath !== 'string') {
+      throw new TypeError('Mumpix.open() requires a file path string');
+    }
+
+    const consistency = opts.consistency || 'eventual';
+    if (!VALID_MODES.includes(consistency)) {
+      throw new Error(`Invalid consistency mode "${consistency}". Valid: ${VALID_MODES.join(', ')}`);
+    }
+
+    const store = new MumpixStore(filePath);
+    store.open({ consistency });
+
+    let auditLog = null;
+    if (consistency === 'verified') {
+      auditLog = new MumpixAudit(filePath);
+      auditLog.open();
+    }
+
+    return new MumpixDB(store, auditLog, { ...opts, consistency });
+  }
+
+  // ─────────────────────────────────────────
+  // Core API
+  // ─────────────────────────────────────────
+
+  /**
+   * Store a memory.
+   *
+   * @param {string} content
+   * @returns {{ id: number, written: boolean, consistency: string }}
+   */
+  async remember(content) {
+    this._assertOpen();
+    if (typeof content !== 'string' || !content.trim()) {
+      throw new TypeError('remember() requires a non-empty string');
+    }
+
+    const record = this._store.write(content);
+
+    if (this._audit) {
+      this._audit.logWrite(record);
+    }
+
+    return {
+      written:     true,
+      id:          record.id,
+      consistency: this._store.header.consistency,
+    };
+  }
+
+  /**
+   * Recall the most semantically relevant memory for a query.
+   *
+   * @param {string} query
+   * @param {object} [opts]
+   * @param {object} [opts.filter]   Pre-filter records: fn(record) → bool
+   * @param {number} [opts.since]    Only consider records newer than this timestamp
+   * @param {string} [opts.mode]     'hybrid' | 'exact' | 'semantic'
+   * @returns {string|null}
+   */
+  async recall(query, opts = {}) {
+    this._assertOpen();
+    if (typeof query !== 'string' || !query.trim()) {
+      throw new TypeError('recall() requires a non-empty string');
+    }
+
+    const records = this._store.all();
+    if (!records.length) return null;
+
+    const t0     = Date.now();
+    const result = await recall(query, records, {
+      embedFn: this._opts.embedFn,
+      ...opts,
+    });
+    const latencyMs = Date.now() - t0;
+
+    if (this._audit) {
+      this._audit.logRecall(query, result, latencyMs);
+    }
+
+    return result ? result.content : null;
+  }
+
+  /**
+   * Return the top-k most relevant memories.
+   *
+   * @param {string} query
+   * @param {number} [k=5]
+   * @param {object} [opts]   Same opts as recall()
+   * @returns {Array<{ id, content, ts, score }>}
+   */
+  async recallMany(query, k = 5, opts = {}) {
+    this._assertOpen();
+    if (typeof query !== 'string' || !query.trim()) {
+      throw new TypeError('recallMany() requires a non-empty string');
+    }
+
+    const records = this._store.all();
+    if (!records.length) return [];
+
+    const results = await recallMany(query, records, {
+      embedFn: this._opts.embedFn,
+      k,
+      ...opts,
+    });
+
+    return results.map(r => ({
+      id:      r.id,
+      content: r.content,
+      ts:      r.ts,
+      score:   r._score,
+    }));
+  }
+
+  /**
+   * List all stored memories.
+   *
+   * @returns {Array<{ id, content, ts }>}
+   */
+  async list() {
+    this._assertOpen();
+    return this._store.all().map(r => ({
+      id:      r.id,
+      content: r.content,
+      ts:      r.ts,
+    }));
+  }
+
+  /**
+   * Delete all memories.
+   *
+   * @returns {{ cleared: boolean, count: number }}
+   */
+  async clear() {
+    this._assertOpen();
+    const count = this._store.clear();
+
+    if (this._audit) {
+      this._audit.logClear(count);
+    }
+
+    return { cleared: true, count };
+  }
+
+  /**
+   * Get audit log entries (Verified mode only).
+   *
+   * @returns {Array<object>}
+   */
+  async audit() {
+    this._assertOpen();
+    if (!this._audit) {
+      throw new Error('audit() requires consistency: "verified". Current mode: ' + this._store.header.consistency);
+    }
+    return this._audit.all();
+  }
+
+  /**
+   * Get audit log summary (Verified mode only).
+   */
+  async auditSummary() {
+    this._assertOpen();
+    if (!this._audit) {
+      throw new Error('auditSummary() requires consistency: "verified"');
+    }
+    return this._audit.summary();
+  }
+
+  /**
+   * Export audit log as NDJSON string (Verified mode only).
+   */
+  async exportAudit() {
+    this._assertOpen();
+    if (!this._audit) {
+      throw new Error('exportAudit() requires consistency: "verified"');
+    }
+    return this._audit.export();
+  }
+
+  /**
+   * Database metadata and stats.
+   */
+  async stats() {
+    this._assertOpen();
+    return this._store.stats();
+  }
+
+  /**
+   * Close the database and release file handles.
+   */
+  async close() {
+    if (this._closed) return;
+    this._store.close();
+    if (this._audit) this._audit.close();
+    this._closed = true;
+  }
+
+  // ─────────────────────────────────────────
+  // Convenience / fluent helpers
+  // ─────────────────────────────────────────
+
+  /**
+   * Add multiple memories at once.
+   *
+   * @param {string[]} items
+   */
+  async rememberAll(items) {
+    this._assertOpen();
+    if (!Array.isArray(items)) throw new TypeError('rememberAll() expects an array');
+    const results = [];
+    for (const item of items) {
+      results.push(await this.remember(item));
+    }
+    return results;
+  }
+
+  /**
+   * Check if any memory semantically matches a query.
+   *
+   * @param {string} query
+   * @returns {boolean}
+   */
+  async has(query) {
+    const result = await this.recall(query);
+    return result !== null;
+  }
+
+  /**
+   * Return the number of stored memories.
+   */
+  get size() {
+    return this._store.records.length;
+  }
+
+  /**
+   * Consistency mode of this instance.
+   */
+  get consistency() {
+    return this._store.header.consistency;
+  }
+
+  /**
+   * File path of the underlying .mumpix file.
+   */
+  get path() {
+    return this._store.filePath;
+  }
+
+  // ─────────────────────────────────────────
+  // Private
+  // ─────────────────────────────────────────
+
+  _assertOpen() {
+    if (this._closed) throw new Error('Database is closed. Call Mumpix.open() again.');
+  }
+}
+
+module.exports = { MumpixDB };

package/src/core/audit.js

@@ -0,0 +1,173 @@
+'use strict';
+
+/**
+ * MumpixAudit — immutable append-only audit log for Verified consistency mode
+ *
+ * Stored alongside the main file: agent.mumpix.audit
+ * Each line is a JSON entry — never modified, only appended.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const AUDIT_SCHEMA_VERSION = 1;
+
+class MumpixAudit {
+  constructor(dbPath) {
+    this.auditPath = path.resolve(dbPath) + '.audit';
+    this._entries  = [];
+    this._fd       = null;
+  }
+
+  open() {
+    if (fs.existsSync(this.auditPath)) {
+      this._load();
+    } else {
+      // Write header
+      const header = {
+        _type:   'audit_header',
+        version: AUDIT_SCHEMA_VERSION,
+        created: Date.now(),
+      };
+      fs.writeFileSync(this.auditPath, JSON.stringify(header) + '\n', 'utf8');
+    }
+    this._fd = fs.openSync(this.auditPath, 'a');
+    return this;
+  }
+
+  close() {
+    if (this._fd !== null) {
+      fs.fdatasyncSync(this._fd);
+      fs.closeSync(this._fd);
+      this._fd = null;
+    }
+  }
+
+  /**
+   * Log a write operation.
+   */
+  logWrite(record) {
+    this._append({
+      _type:   'write',
+      id:      record.id,
+      hash:    record.h,
+      len:     record.content.length,
+      ts:      Date.now(),
+    });
+  }
+
+  /**
+   * Log a recall operation.
+   */
+  logRecall(query, result, latencyMs) {
+    this._append({
+      _type:     'recall',
+      queryHash: this._hash(query),
+      queryLen:  query.length,
+      resultId:  result ? result.id : null,
+      resultHash: result ? result.h : null,
+      score:     result ? result._score : null,
+      latencyMs: Math.round(latencyMs * 100) / 100,
+      ts:        Date.now(),
+    });
+  }
+
+  /**
+   * Log a clear operation.
+   */
+  logClear(count) {
+    this._append({
+      _type:  'clear',
+      count,
+      ts:     Date.now(),
+    });
+  }
+
+  /**
+   * Log a consistency mode change.
+   */
+  logModeChange(from, to) {
+    this._append({
+      _type: 'mode_change',
+      from,
+      to,
+      ts:    Date.now(),
+    });
+  }
+
+  /**
+   * Return all audit entries (excluding header).
+   */
+  all() {
+    return this._entries.map(e => ({ ...e }));
+  }
+
+  /**
+   * Return entries filtered by type.
+   */
+  filter(type) {
+    return this._entries.filter(e => e._type === type).map(e => ({ ...e }));
+  }
+
+  /**
+   * Return a compact summary.
+   */
+  summary() {
+    const writes  = this._entries.filter(e => e._type === 'write').length;
+    const recalls = this._entries.filter(e => e._type === 'recall').length;
+    const clears  = this._entries.filter(e => e._type === 'clear').length;
+    const first   = this._entries[0];
+    const last    = this._entries[this._entries.length - 1];
+
+    return {
+      totalEntries: this._entries.length,
+      writes,
+      recalls,
+      clears,
+      firstEventAt: first ? first.ts : null,
+      lastEventAt:  last  ? last.ts  : null,
+      auditPath:    this.auditPath,
+    };
+  }
+
+  /**
+   * Export as NDJSON string (for compliance hand-off).
+   */
+  export() {
+    return this._entries.map(e => JSON.stringify(e)).join('\n');
+  }
+
+  // ── Private ────────────────────────────────────
+
+  _append(entry) {
+    const line = JSON.stringify(entry) + '\n';
+    fs.writeSync(this._fd, line, null, 'utf8');
+    fs.fdatasyncSync(this._fd);
+    this._entries.push(entry);
+  }
+
+  _load() {
+    const raw   = fs.readFileSync(this.auditPath, 'utf8');
+    const lines = raw.split('\n').filter(l => l.trim());
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (entry._type && entry._type !== 'audit_header') {
+          this._entries.push(entry);
+        }
+      } catch (_) { /* skip corrupt lines */ }
+    }
+  }
+
+  _hash(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+      h ^= s.charCodeAt(i);
+      h  = Math.imul(h, 0x01000193);
+    }
+    return '0x' + (h >>> 0).toString(16).padStart(8, '0');
+  }
+}
+
+module.exports = { MumpixAudit };