mumpix 1.0.17 → 1.0.18

package/LICENSE

@@ -1,20 +1,19 @@
-MUMPIX PROPRIETARY LICENSE
-Copyright (c) 2026 Mumpix (vdsx.cloud). All Rights Reserved.
+Mumpix Business Source License 1.1 (BUSL-1.1)
+Copyright (c) 2026 Mumpix (VDSX). All rights reserved.
 
-COMMERCIAL RESTRICTED USE LICENSE
+Licensed under the Business Source License 1.1 (the "License").
+You may obtain a copy of the License terms from Licensor.
 
-This software and associated documentation files (the "Software") are proprietary to Mumpix. 
+Use Grant:
+- Non-production use, evaluation, and internal development are permitted.
+- Production use requires a commercial agreement with Licensor.
 
-1. NON-COMMERCIAL USE: Permission is hereby granted, free of charge, to any person obtaining a copy of this Software, to use the Software for personal, educational, or non-commercial research purposes only.
+Restrictions:
+- You may not offer the software as a competing hosted or embedded commercial service without a commercial license.
+- You may not remove or alter proprietary notices.
 
-2. COMMERCIAL RESTRICTIONS: ANY COMMERCIAL USE, INCLUDING BUT NOT LIMITED TO:
-   - USING THE SOFTWARE AS PART OF A PAID SERVICE OR PRODUCT
-   - USING THE SOFTWARE FOR INTERNAL BUSINESS OPERATIONS
-   - REDISTRIBUTING THE SOFTWARE FOR PROFIT
-   IS STRICTLY PROHIBITED WITHOUT AN EXPLICIT COMMERCIAL LICENSE FROM MUMPIX (vdsx.cloud).
+Change Date:
+- This package remains source-available under BUSL-1.1 unless and until Licensor publishes an updated license grant.
 
-3. MODIFICATIONS: You may modify the Software for personal use, but you may not redistribute modified versions under any license that allows commercial use.
-
-4. NO WARRANTY: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY.
-
-By using this Software, you agree to these terms. For commercial licensing inquiries, contact license@vdsx.cloud.
+This software is provided "AS IS", without warranty of any kind.
+For commercial licensing: license@vdsx.cloud

package/README.md

@@ -1,396 +1,192 @@
 # Mumpix
 
-**SQLite for AI** — embedded, zero-config memory database for AI agents and LLM applications.
+MumpixDB is the reasoning ledger and structured memory engine for AI systems.
 
 ```bash
 npm install mumpix
 ```
 
----
+## What this package is
 
-## Why Mumpix?
+The `mumpix` npm package is the Node package for MumpixDB.
 
-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.
+It is built for:
 
-- **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
+- durable AI memory
+- ordered reasoning state
+- replayable context
+- local-first storage
+- audit-friendly execution
 
----
+Core thesis:
 
-## Quickstart
-
-```js
-const { Mumpix } = require('mumpix')
+> Git stores what changed. MumpixDB stores why.
 
-// Open (or create) a local database
-const db = await Mumpix.open('./agent.mumpix', { consistency: 'eventual' })
+This package is the database layer. It is separate from higher-level products built on top of MumpixDB, including WYD Code.
 
-// Store memories
-await db.remember('User prefers TypeScript over JavaScript')
-await db.remember('Project uses pnpm workspaces')
+## Why MumpixDB
 
-// 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()
-```
+Most AI systems fail at the memory layer, not the model layer.
 
----
+MumpixDB gives you:
 
-## API
+- local-first storage in a `.mumpix` file
+- append-oriented durable state
+- strict and verified execution modes
+- replayable memory and audit surfaces
+- semantic recall and exact recall
+- a structured API for long-running assistants, workflows, and applications
 
-### Developer SDK (HTTP Client)
-
-For developers integrating Mumpix-backed services (local runner, benchmark APIs, hosted tools):
+## Quickstart
 
 ```js
-const { MumpixDevClient } = require('mumpix')
+const { Mumpix } = require('mumpix');
 
-const client = new MumpixDevClient({
-  baseUrl: 'https://mumpixdb.com/benchmark'
-})
+async function main() {
+  const db = await Mumpix.open('./reasoning.mumpix', { consistency: 'eventual' });
 
-const health = await client.health()
-await client.remember('user likes concise answers')
-const hit = await client.recall('what does the user like?')
-const stats = await client.stats()
-```
+  await db.remember('User prefers short, direct answers');
+  await db.remember('Project auth expiry changed from 30min to 15min');
 
-### `MumpixDevClient` methods
+  const answer = await db.recall('what style does the user prefer?');
+  console.log(answer);
 
-- `health()`
-- `remember(content)`
-- `recall(query)`
-- `recallMany(query, k)`
-- `memories()`
-- `clear()`
-- `stats()`
-- `settings()`
-- `updateSettings(patch)`
-- `files()`
-- `readFile(file, { atTs, source })`
-- `timeline(file, { source })`
-- `exportUrl(file, format, { atTs, source })`
-- `roms()`
-- `manualForRom(file)`
-- `manualViewUrl(file, { isolate, v })`
+  const stats = await db.stats();
+  console.log(stats);
 
-Errors are thrown as `MumpixApiError` with `.status` and `.data` fields.
+  await db.close();
+}
 
----
+main().catch(console.error);
+```
 
-### `Mumpix.open(filePath, [opts])` → `Promise<MumpixDB>`
+## Core API
 
-Opens (or creates) a Mumpix database.
+### `Mumpix.open(filePath, [opts])`
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `consistency` | `string` | `'eventual'` | `'eventual'` / `'strict'` / `'verified'` |
-| `embedFn` | `async fn(texts[]) → number[][]` | — | Custom embedding function (OpenAI, Cohere, etc.) |
+Opens or creates a local MumpixDB file.
 
-Note: `strict` and `verified` are tier-gated capabilities. Without an active paid license, paid mode requests are blocked or downgraded to `eventual` based on license state.
+```js
+const db = await Mumpix.open('./agent.mumpix', {
+  consistency: 'eventual'
+});
+```
 
-### Consistency modes
+Options:
 
-| Mode | Write behaviour | Audit log | Use case |
+| Option | Type | Default | Description |
 |---|---|---|---|
-| `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 |
-
----
+| `consistency` | `string` | `'eventual'` | `'eventual'`, `'strict'`, or `'verified'` |
+| `embedFn` | `async function` | — | Custom embedding function for semantic recall |
 
 ### 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 = await Mumpix.open('./compliance.mumpix', { consistency: 'verified' })
+await db.remember(text);
+await db.rememberAll(['one', 'two']);
 
-// Full audit log
-await db.audit()
-// → [{ _type, id, hash, ts, ... }, ...]
+await db.recall(query);
+await db.recallMany(query, 5);
 
-// 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
+await db.has(query);
+await db.list();
+await db.clear();
+await db.stats();
+await db.close();
 ```
 
-### 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
-})
+### Consistency modes
 
-await db.recallMany(query, 5, { mode: 'semantic' })
-```
+| Mode | Behavior | Use case |
+|---|---|---|
+| `eventual` | fast local writes | prototypes, local tools, development |
+| `strict` | stronger durability path | production agents and application state |
+| `verified` | durability + audit surfaces | regulated, auditable, or compliance-heavy workloads |
 
-### Custom embeddings (OpenAI, Cohere, etc.)
+### Verified mode methods
 
 ```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 = await Mumpix.open('./verified.mumpix', { consistency: 'verified' });
 
-const db = await Mumpix.open('./agent.mumpix', { consistency: 'strict', embedFn })
-// db.recall() and db.recallMany() now use OpenAI embeddings automatically
+await db.audit();
+await db.auditSummary();
+await db.exportAudit();
 ```
 
----
-
-## LangChain integration
-
-```js
-const { Mumpix } = require('mumpix')
-const { MumpixVectorStore, MumpixChatMemory, MumpixRetriever } = require('mumpix/src/integrations/langchain')
-
-const db = await 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')
-```
+## Developer SDK
 
-## LlamaIndex integration
+This package also includes a developer client for Mumpix-backed services.
 
 ```js
-const { Mumpix } = require('mumpix')
-const { MumpixIndex, MumpixReader } = require('mumpix/src/integrations/llamaindex')
+const { MumpixDevClient } = require('mumpix');
 
-const db = await 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
-```
-
-Note: CLI strict/verified modes are tier-gated the same as SDK/API mode selection.
-
----
-
-## File format
-
-The `.mumpix` file is plain NDJSON — human-readable, portable, no binary parser required:
+const client = new MumpixDevClient({
+  baseUrl: 'https://mumpixdb.com/benchmark'
+});
 
-```
-{"v":1,"consistency":"strict","created":1740000000000,"path":"agent.mumpix"}
-{"id":1,"content":"User prefers TypeScript","ts":1740000001000,"h":"hmac256:..."}
-{"id":2,"content":"Use pnpm workspaces","ts":1740000002000,"h":"hmac256:..."}
+const health = await client.health();
+const stats = await client.stats();
 ```
 
-**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
+Available client methods:
 
-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.
+- `health()`
+- `remember(content)`
+- `recall(query)`
+- `recallMany(query, k)`
+- `memories()`
+- `clear()`
+- `stats()`
+- `settings()`
+- `updateSettings(patch)`
+- `files()`
+- `readFile(file, { atTs, source })`
+- `timeline(file, { source })`
+- `exportUrl(file, format, { atTs, source })`
+- `roms()`
+- `manualForRom(file)`
+- `manualViewUrl(file, { isolate, v })`
 
----
+## Integrations
 
-## Examples
+This package includes adapters for:
 
-```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
-npm run verify:claims           # executable truth-audit for package claims
-```
+- LangChain
+- LlamaIndex
 
-### Release maintenance
+Examples:
 
 ```bash
-# Publish current version and deprecate all older npm versions
-npm run release:publish-and-deprecate -- --otp=123456
-
-# Optional flags:
-# --skip-verify   skip verify:claims
-# --skip-publish  only deprecate older versions
-# --dry-run       no writes to npm
-# --remove-old    try to unpublish old versions; deprecate on failure
-```
-
----
-
-## Requirements
-
-- Node.js >= 18
-- Zero runtime dependencies
-
----
-
-## License
-
-Proprietary — COMMERCIAL RESTRICTED. See [LICENSE](LICENSE) for terms.
-Copyright © 2026 Mumpix (vdsx.cloud). All Rights Reserved.
-
----
-
-## Licensing & Tiers
-
-Mumpix uses capability-based tiering: community is for building, paid tiers are for production operation and compliance.
-
-| Capability | Community (Free) | Developer ($19/mo) | Teams ($79/mo) | Compliance ($5K/mo) |
-|---|---|---|---|---|
-| `eventual` mode | ✅ | ✅ | ✅ | ✅ |
-| `strict` mode | ❌ | ✅ | ✅ | ✅ |
-| `verified` mode | ❌ | ❌ | ❌ | ✅ |
-| Record writes | Unlimited | Unlimited | Unlimited | Unlimited |
-| Offline use | ✅ | ✅ | ✅ | ✅ |
-
-### Tier intent
-
-- **Community**: build and prototype with full local development flow.
-- **Developer**: unlock production durability via `strict`.
-- **Teams**: same core durability plus team/commercial operations.
-- **Compliance**: regulated workflows with `verified` audit capabilities.
-
-### Offline/Air-gapped expiry policy
-
-- Monthly licenses use a **45-day offline lease window** by default.
-- Enterprise/government/compliance licenses support long/custom lease windows (for example 5-year, 10-year, or custom).
-- When a paid license is expired, requested paid modes are automatically downgraded to `eventual` until renewal.
-
-You can tune lease windows with environment variables:
-
-- `MUMPIX_LICENSE_MAX_DAYS_MONTHLY` (default `45`)
-- `MUMPIX_LICENSE_MAX_DAYS_ENTERPRISE` (default `36500`)
-- `MUMPIX_LICENSE_MAX_DAYS_GOVERNMENT` (default `36500`)
-- `MUMPIX_LICENSE_MAX_DAYS_COMPLIANCE` (default `36500`)
-
-### Using a License Key
-
-```javascript
-const db = await Mumpix.open('./agent.mumpix', {
-  licenseKey: 'your-license-key-here'
-});
+node examples/langchain-adapter.js
+node examples/llamaindex-adapter.js
 ```
 
-Get your key at [mumpixdb.com](https://mumpixdb.com).
-
-### No-Key account login (recommended)
-
-You can link your paid account once and let Mumpix load the local signed license automatically:
+## CLI
 
 ```bash
-mumpix auth login            # device flow (browser-based)
-mumpix auth status
+npm install -g mumpix
 ```
 
-Advanced login options:
+Then:
 
 ```bash
-mumpix auth login --token=<account-token>      # backend token exchange
-mumpix auth login --license=<signed-license>   # direct import
-mumpix auth logout
+mumpix --help
 ```
 
-For `--token` exchange, your backend should expose `/api/mumpix/auth/token/exchange` and map account tokens server-side (for example via `MUMPIX_AUTH_TOKEN_MAP`), not raw user IDs.
+## Package boundary
 
-By default, auth state is stored at `~/.config/mumpix/auth.json` (or `%APPDATA%/mumpix/auth.json` on Windows).
+The `mumpix` package is the MumpixDB package.
 
-### Install-time auth flow
+It is not:
 
-On `npm install mumpix`, the package runs an install-time auth prompt in interactive terminals:
+- the WYD Code CLI
+- the WYD Code MCP bridge
+- the website product shell
 
-- Press **Enter**: opens Mumpix in your browser and links account access for paid modes.
-- Press any other key: install continues in `eventual` mode only.
-- If browser auth is cancelled/fails, install continues in `eventual` mode.
+Those are separate layers and separate distributions.
 
-Non-interactive installs (CI/containers) skip this prompt automatically and default to `eventual`.
+## Links
 
-Auth endpoint fallback:
-- CLI tries `https://mumpixdb.com` first, then automatically retries `https://mumpixdb.com/benchmark` on 404.
-- Override with `MUMPIX_AUTH_BASE_URL` if your auth API is hosted elsewhere.
+- Website: [https://mumpixdb.com](https://mumpixdb.com)
+- Benchmark: [https://mumpixdb.com/benchmark](https://mumpixdb.com/benchmark)
+- Docs: [https://mumpixdb.com](https://mumpixdb.com)

package/examples/langchain-adapter.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { Mumpix } = require('../src/index');
+const {
+  MumpixVectorStore,
+  MumpixChatMemory,
+  MumpixRetriever,
+} = require('../src/integrations/langchain');
+
+async function main() {
+  const db = await Mumpix.open('./langchain-adapter-example.mumpix', {
+    consistency: 'eventual',
+  });
+
+  const store = new MumpixVectorStore(db);
+  await store.addTexts([
+    'User likes concise answers',
+    'Project uses TypeScript',
+  ]);
+
+  const docs = await store.similaritySearch('what language is used?', 2);
+  console.log('similaritySearch ->', docs);
+
+  const memory = new MumpixChatMemory({ db, k: 3 });
+  await memory.saveContext(
+    { input: 'What stack do we use?' },
+    { output: 'TypeScript and Node.js' },
+  );
+  const loaded = await memory.loadMemoryVariables({ input: 'language stack' });
+  console.log('chatMemory ->', loaded);
+
+  const retriever = new MumpixRetriever(db, { k: 2 });
+  const relevant = await retriever.getRelevantDocuments('concise');
+  console.log('retriever ->', relevant);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error('langchain-adapter example failed:', error?.message || String(error));
+  process.exit(1);
+});

package/examples/llamaindex-adapter.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { Mumpix } = require('../src/index');
+const {
+  MumpixIndex,
+  MumpixReader,
+} = require('../src/integrations/llamaindex');
+
+async function main() {
+  const db = await Mumpix.open('./llamaindex-adapter-example.mumpix', {
+    consistency: 'eventual',
+  });
+
+  const index = new MumpixIndex(db);
+  await index.insert('The team prefers short and direct answers');
+  await index.insert({ text: 'The default runtime is Node.js' });
+
+  const retriever = index.asRetriever({ topK: 2 });
+  const nodes = await retriever.retrieve('runtime preference');
+  console.log('retrieve ->', nodes);
+
+  const reader = new MumpixReader(db);
+  const docs = await reader.loadData();
+  console.log('loadData ->', docs);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error('llamaindex-adapter example failed:', error?.message || String(error));
+  process.exit(1);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mumpix",
-  "version": "1.0.17",
-  "description": "SQLite for AI — embedded, zero-config memory database for AI agents and LLM applications",
+  "version": "1.0.18",
+  "description": "MumpixDB reasoning ledger and structured memory engine for AI systems",
   "main": "src/index.js",
   "bin": {
     "mumpix": "bin/mumpix.js"
@@ -17,6 +17,11 @@
     "ai",
     "memory",
     "database",
+    "reasoning-ledger",
+    "reasoning",
+    "context",
+    "replay",
+    "audit",
     "embedded",
     "vector",
     "semantic",
@@ -30,13 +35,18 @@
     "rag"
   ],
   "author": "Mumpix",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "BUSL-1.1",
+  "homepage": "https://mumpixdb.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mumpix/mumpix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mumpix/mumpix/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
-  "dependencies": {
-    "mumpix": "^1.0.14"
-  },
   "files": [
     "src/",
     "bin/",
@@ -45,6 +55,5 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
-  ],
-  "homepage": "https://mumpixdb.com"
+  ]
 }

package/src/integrations/developer-sdk.js

@@ -70,8 +70,16 @@ class MumpixDevClient {
     return this._request('/api/health');
   }
 
-  remember(content) {
-    return this._request('/remember', { method: 'POST', body: { content } });
+  async remember(content) {
+    // Primary app API expects `text`. Keep `content` fallback for older endpoints.
+    try {
+      return await this._request('/remember', { method: 'POST', body: { text: content } });
+    } catch (error) {
+      if (error && Number(error.status) === 400) {
+        return this._request('/remember', { method: 'POST', body: { content } });
+      }
+      throw error;
+    }
   }
 
   recall(query) {
@@ -155,4 +163,3 @@ module.exports = {
   MumpixDevClient,
   MumpixApiError,
 };
-