mumpix 1.0.17 → 1.0.19

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.19 - 2026-04-13
+
+### Internal & Sync
+- Synchronized latest temporal engine and operator scripts from core module into the package tree.
+- Configured embedded GGUF agent context window ceilings (8K) to prevent VRAM memory allocation conflicts with local LLMs (e.g., `mumpix-mlc-llm`).
+
+## 1.0.18 - 2026-03-30
+- General performance and sync updates
+
+## 1.0.17 - 2026-03-24
+- Core temporal sync patches
+
 ## 1.0.11 - 2026-03-03
 
 ## 1.0.12 - 2026-03-03

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,256 @@
 # 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')
-
-// Open (or create) a local database
-const db = await Mumpix.open('./agent.mumpix', { consistency: 'eventual' })
+> Git stores what changed. MumpixDB stores why.
 
-// Store memories
-await db.remember('User prefers TypeScript over JavaScript')
-await db.remember('Project uses pnpm workspaces')
+This package is the database layer. It is separate from higher-level products built on top of MumpixDB, including WYD Code.
 
-// 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'
+## Why MumpixDB
 
-await db.close()
-```
-
----
+Most AI systems fail at the memory layer, not the model layer.
 
-## API
+MumpixDB gives you:
 
-### Developer SDK (HTTP Client)
+- 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
 
-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' }
+await db.remember(text);
+await db.rememberAll(['one', 'two']);
 
-// Recall the best semantic match
-await db.recall(query)
-// → 'User prefers TypeScript over JavaScript'   or   null
+await db.recall(query);
+await db.recallMany(query, 5);
 
-// 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()
+await db.has(query);
+await db.list();
+await db.clear();
+await db.stats();
+await db.close();
 ```
 
-### Verified-mode methods
+### Temporal API
 
-```js
-const db = await Mumpix.open('./compliance.mumpix', { consistency: 'verified' })
+`mumpix` also exposes a deterministic temporal layer built on top of WAL-backed records.
 
-// 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
+This is meant to answer timeline questions by computing over normalized events, not by asking a model to guess from raw text.
 
 ```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
-})
+const { Mumpix } = require('mumpix');
 
-await db.recallMany(query, 5, { mode: 'semantic' })
-```
-
-### Custom embeddings (OpenAI, Cohere, etc.)
+const db = await Mumpix.open('./agent.mumpix', { consistency: 'eventual' });
 
-```js
-const { Mumpix } = require('mumpix')
-const OpenAI = require('openai')
+await db.remember({
+  content: 'I set up the smart thermostat on March 1st.',
+  workspace: 'home',
+  repo: 'infra-home',
+  source: 'ops-log',
+  ts: Date.parse('2026-03-03T09:10:00Z'),
+});
 
-const client = new OpenAI()
+await db.remember({
+  content: 'I set up the mesh network system on March 3rd.',
+  workspace: 'home',
+  repo: 'infra-home',
+  source: 'ops-log',
+  ts: Date.parse('2026-03-03T09:00:00Z'),
+});
 
-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 events = await db.events();
+const index = await db.eventIndex();
+const result = await db.temporalQuery(
+  'Which device did I set up first, the smart thermostat or the mesh network system?'
+);
 
-const db = await Mumpix.open('./agent.mumpix', { consistency: 'strict', embedFn })
-// db.recall() and db.recallMany() now use OpenAI embeddings automatically
+console.log(events.length);
+console.log(Array.from(index.byWorkspace.keys()));
+console.log(result.value); // smart thermostat
 ```
 
----
-
-## 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' })
+Available temporal package APIs:
 
-// As a VectorStore
-const store = new MumpixVectorStore(db)
-await store.addTexts(['preference 1', 'preference 2'])
-const docs = await store.similaritySearch('query', 4)
+- `db.events({ query?, topK? })`
+- `db.eventIndex({ query?, topK? })`
+- `db.temporalQuery(query, { topK?, now? })`
 
-// 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
+Low-level exports are also available for advanced use:
 
 ```js
-const { Mumpix } = require('mumpix')
-const { MumpixIndex, MumpixReader } = require('mumpix/src/integrations/llamaindex')
-
-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()
+const { temporal, temporalEngine, temporalIndexes } = require('mumpix');
 ```
 
----
+These expose:
 
-## CLI
+- deterministic event operators
+- event materialization
+- event indexing by title, type, workspace, repo, and source
 
-```bash
-# Global install
-npm install -g mumpix
+Temporal records support scoped metadata on write:
 
-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
-```
+- `workspace`
+- `repo`
+- `source`
+- `ts`
 
-Note: CLI strict/verified modes are tier-gated the same as SDK/API mode selection.
+### Consistency modes
 
----
+| 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 |
 
-## File format
+### Verified mode methods
 
-The `.mumpix` file is plain NDJSON — human-readable, portable, no binary parser required:
+```js
+const db = await Mumpix.open('./verified.mumpix', { consistency: 'verified' });
 
+await db.audit();
+await db.auditSummary();
+await db.exportAudit();
 ```
-{"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:..."}
-```
-
-**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.
+## Developer SDK
 
-**Audit log**: In `verified` mode, an additional `.mumpix.audit` file is created. It is append-only, never modified, and `fdatasync`'d after every entry.
+This package also includes a developer client for Mumpix-backed services.
 
----
-
-## 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
-npm run verify:claims           # executable truth-audit for package claims
-```
+```js
+const { MumpixDevClient } = require('mumpix');
 
-### Release maintenance
+const client = new MumpixDevClient({
+  baseUrl: 'https://mumpixdb.com/benchmark'
+});
 
-```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
+const health = await client.health();
+const stats = await client.stats();
 ```
 
----
-
-## Requirements
-
-- Node.js >= 18
-- Zero runtime dependencies
-
----
-
-## License
-
-Proprietary — COMMERCIAL RESTRICTED. See [LICENSE](LICENSE) for terms.
-Copyright © 2026 Mumpix (vdsx.cloud). All Rights Reserved.
+Available client methods:
 
----
-
-## 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
+- `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 })`
 
-- 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.
+## Integrations
 
-You can tune lease windows with environment variables:
+This package includes adapters for:
 
-- `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`)
+- LangChain
+- LlamaIndex
 
-### Using a License Key
+Examples:
 
-```javascript
-const db = await Mumpix.open('./agent.mumpix', {
-  licenseKey: 'your-license-key-here'
-});
+```bash
+node examples/langchain-adapter.js
+node examples/llamaindex-adapter.js
+node examples/temporal-memory.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);
+});