⚡ DUMEdb (Deterministic Unit-Record Memory Engine)

Hardware-aligned, zero-prompt-bloat, byte-structured memory engine, production Model Context Protocol (MCP) server, and drop-in OpenAI-compatible proxy gateway for autonomous AI agents.

🎬 Watch the Official Walkthrough on YouTube:
Stop Force-Feeding Your AI 30,000 Tokens just to remind them who you are! — Featuring Frank, The Sentinel, and real-time live benchmarks.

🧭 Why DUMEdb?

Modern AI agents suffer from context rot, hallucination creep, and quadratic token bills when state is stuffed into raw conversation transcripts or retrieved fuzzily from high-dimensional vector databases.

Traditional Agent Memory (Context Stuffing):
[ System Prompt ] + [ 200 Turn Transcript Dump (85,000 tokens) ] + [ 10 Vector Chunks ] = 💥 Context Rot & High Cost

DUMEdb Memory Substrate:
[ System Prompt ] + [ Discrete 32-Byte Hardware Registers (220 tokens) ] + [ Active Turn ] = ⚡ 100% Deterministic & Instant

DUMEdb replaces conversational bloat with discrete, deterministic 32-byte binary registers stored in a memory-mapped database (LMDB). AI models read and mutate active state in microseconds with zero prompt bloat.

Related MCP server: contextgit

🔬 Binary Anatomy: The 32-Byte Unit Record

At the hardware core of DUMEdb is the Unit Record—a strictly aligned, 32-byte C-struct packed without pointer indirection:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
|                  ENTITY_ID (128-bit UUID)                     |
|                                                               |
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          OPCODE (uint16)      |         FLAGS (uint16)        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                     TIMESTAMP (uint32 Unix)                   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
|                    VALUE / PAYLOAD (64-bit)                   |
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

• Entity UUID (16 bytes): Content-addressed or namespace-isolated actor/agent identity.

• Opcode (2 bytes): Schema-mapped semantic key (1001-65534).

• Flags (2 bytes): Bitfield indicating Active state, Float encoding, or Extension Payload pointer.

• Timestamp (4 bytes): Monotonic 32-bit second timestamp.

• Value (8 bytes): Inline immediate data (64-bit Int, IEEE-754 Float, Enum index, or SHA-256 payload hash reference).

⚡ Core Subsystems

1. 🔌 Model Context Protocol (MCP) Server (dume.mcp_server)

Full compliance with Anthropic's Model Context Protocol (MCP) specification over standard I/O (stdio):

• 15 First-Class MCP Tools: Provides direct tools for state reading (dume_read_state), transactional register mutation (dume_commit_state), filtered queries (dume_query), and dynamic schema cataloging (dume_list_schemas).

• Autonomous Session Orientation: Full Cabinet integration (cabinet_wake, cabinet_refresh) enabling zero-turn workspace context hydration.

• Plug-and-Play IDE Compatibility: Plugs directly into Claude Desktop, Cursor, Antigravity, Windsurf, and Cline with zero external network dependencies.

• Self-Healing Background Daemon: Automatically ensures local memory substrates and HTTP inspectors are active whenever the MCP harness starts.

2. 📁 Recursive Directory Ingestion Engine

Ingest entire software repositories, project documentation, or knowledge folders into deterministic state registers with a single call:

• Recursive Directory Crawler: Discovers and digests file trees while pruning noise (.git, node_modules, .venv, binaries).

• SHA-256 Content Deduplication: Identical files across locations are deduplicated in memory.

• Automatic Opcode Minting: Novel fields and parameters automatically mint clean, schema-typed opcodes in the 2001-65534 space.

• Atomic Single-Transaction LMDB Commits: Thousands of registers are persisted in milliseconds.

3. 🔄 OpenAI Universal Proxy Gateway (/v1)

Drop-in compatibility with any AI client: Cursor, Claude Desktop, VS Code (Cline), OpenWebUI, LangChain, or raw cURL.

• Intercepts requests pointing to http://localhost:8095/v1.

• Injects deterministic state registers ([DUME_STATE ...]) into the active prompt prefix with microsecond speed.

• Passes streaming completions transparently to upstream models (Ollama, vLLM, Groq, OpenAI, Anthropic).

• Automatically scribes assistant mutations in the background.

4. 🎛️ Dual-View Web Inspector

A visual cockpit for inspecting and managing agent memory in real time:

• Dual View: Switch between interactive cards and raw hardware hex dumps.

• Real-Time WebSocket Sync: Live updates as agents commit mutations.

• Directory Ingestion Modal: Instant folder crawling with one click.

• Token Telemetry & KV-Cache Runway: Real-time context monitoring.

5. 🗄️ The Cabinet (Zero-Turn Hydration & Session Continuity Ledger)

The antidote to the "80KB backpack" of conversational bloat and agent amnesia. Instead of force-feeding an AI model 25,000 tokens of raw historical transcripts or running fuzzy filesystem searches (ripgrep) just to figure out "where were we?", The Cabinet provides an instant, deterministic operational compass:

• Zero-Turn Orientation (cabinet_wake): Hydrates the agent with verified operator identity, active memory registers, permanent invariants, and immediate next milestones in a single turn under ~220 tokens with < 0.8 μs LMDB read latency.

• Predictable Session Handoff (cabinet_refresh): Before an IDE auto-compaction lobotomizes an agent at 70% context, the Sentinel stamps a high-density tactical receipt—recording completed work, files touched, and immediate next handshakes—allowing fresh sessions to boot with a 99.8% clean context runway.

• Permanent Invariants & Behavioral Laws (cabinet_mint_rule): Persists non-negotiable architectural rules, terminology protocols, and operational guardrails into hardware registers that survive restarts and never get washed away in chat history.

• Tactical Workflow Playbooks (cabinet_record_workflow): Stores versioned, step-by-step procedures directly in deterministic memory, enabling agents to execute complex operations without re-deriving plans from scratch.

• Eliminates Filesystem Rummaging: Prohibits expensive, blind directory scans—agents know their exact mission, state, and next moves from the very first turn.

🚀 Quick Start (60 Seconds)

1. Installation

# Clone repository
git clone https://github.com/madbradsmith/DUMEdb.git
cd DUMEdb

# Install editable package
pip install -e .

2. Start the Engine & Inspector

# Start server (default port: 8095)
python -m dume --port 8095

# Or on Windows:
Start_DUMEdb_UI.bat

# Or on macOS/Linux:
./start_dumedb.sh

Console Output:

=======================================================
🚀 DUMEdb Studio v1.2.2 is Live!
🔗 Web Inspector: http://localhost:8095/inspector/index.html
⚡ Proxy Gateway: http://localhost:8095/v1
=======================================================

Open your browser to: http://localhost:8095/inspector/index.html

🔌 Connecting to Your Agent Tools

1. Model Context Protocol (MCP) — Claude Desktop, Cursor, Antigravity

DUMEdb is a native MCP server exposing deterministic memory tools over stdio. Add it to your client configuration:

Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "dumedb": {
      "command": "python",
      "args": ["-m", "dume.mcp_server"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Or via Docker:

{
  "mcpServers": {
    "dumedb": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "madbradsmith/dumedb"]
    }
  }
}

Key MCP Tools Included:

• dume_read_state: Reads active registers for an entity directly from LMDB with zero prompt bloat.

• dume_commit_state: Transactionally writes 32-byte unit-record registers.

• dume_query: Queries memory registers with opcode and entity filtering.

• cabinet_wake: Zero-turn workspace orientation and memory retrieval.

• cabinet_refresh: Flushes session progress and odometers to disk for the next agent instance.

2. OpenAI Proxy Gateway — Cursor / VS Code (Cline / Continue)

Point your model base URL to the DUMEdb local proxy gateway:

{
  "openai.baseUrl": "http://localhost:8095/v1",
  "openai.apiKey": "dume-local"
}

Python SDK / OpenAI Client

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8095/v1",
    api_key="dume-local"
)

response = client.chat.completions.create(
    model="llama3",
    messages=[
        {"role": "user", "content": "What is our current project status?"}
    ],
    extra_headers={"X-Entity-ID": "MadBrad-Nostra-01"}
)

print(response.choices[0].message.content)

Ingest a Directory via CLI / cURL

# Via cURL
curl -X POST http://localhost:8095/dume/ingest/directory \
  -H "Content-Type: application/json" \
  -H "X-Entity-ID: Project-Alpha" \
  -d '{"directory_path": "C:/Projects/MyAwesomeRepo", "recursive": true}'

# Via Python
from dume.intake.directory_reducer import DirectoryReducer

result = DirectoryReducer.reduce_directory("C:/Projects/MyAwesomeRepo")
print(f"Ingested {result['files_ingested']} files into {result['total_registers_extracted']} registers in {result['duration_ms']}ms.")

📐 Architecture Overview

                         ┌────────────────────────────────────────┐
                         │   Autonomous Agent / IDE / Chat UI     │
                         │   (Cursor, Claude Desktop, LangChain)  │
                         └───────────────────┬────────────────────┘
                                             │  OpenAI-Compatible
                                             ▼  HTTP /v1
                         ┌────────────────────────────────────────┐
                         │         DUME Universal Proxy           │
                         │  - Header entity resolution            │
                         │  - Context prefix assembly (<0.8μs)    │
                         │  - Inline directive parser (!set)      │
                         └───────┬────────────────────────┬───────┘
                                 │                        │
               Read/Write Mmap   │                        │ Async Pipeline
                                 ▼                        ▼
     ┌────────────────────────────────────┐    ┌─────────────────────────┐
     │      LMDB Memory Substrate         │    │   Scribe Worker Queue   │
     │  - 32-Byte Unit Records            │    │  - Mutation validation  │
     │  - Multi-version concurrency (MVCC)│    │  - WebSocket broadcast  │
     │  - Zero-copy binary struct unpack  │    └────────────┬────────────┘
     └────────────────────────────────────┘                 │
                                 ▲                          ▼
                                 │              ┌────────────────────────┐
                                 └──────────────┤  Dynamic Schema Dict   │
                                                │  - 65k Opcode Manager  │
                                                │  - JSON Disk Catalog   │
                                                └────────────────────────┘

🧪 Testing

DUMEdb includes a comprehensive pytest suite covering the core memory engine, LMDB concurrency, schema dictionaries, directory ingestion, and the OpenAI proxy substrate:

pytest tests/

☕ Support & GitHub Sponsors

If DUMEdb has saved your AI agents from context rot, slashed your API token bills, or improved your autonomous workflows, please consider supporting the project:

• ❤️ Sponsor MadBrad on GitHub

• ⭐ Star this repository to help other engineers discover deterministic memory

• 🗣️ Share the Masterclass with teams building production agent architectures

💼 Custom Features & Enterprise Deployments

Need DUMEdb tailored for a specialized agent framework, private cloud, or enterprise pipeline?

MadBrad is available for hire on a consulting / fee basis for:

• Custom Agent Substrates: Custom MCP servers, IDE integrations (Cursor, Claude Code, Windsurf, Antigravity), or tailored schema mappings for your proprietary data.

• Enterprise Deployments: Hardened on-premise LMDB memory clusters, automated multi-agent synchronization, and deterministic hydration bridges.

• High-Throughput Optimizations: Sub-microsecond binary state architectures for demanding production workloads.

To inquire about custom feature development or enterprise support, reach out via GitHub Sponsors or open a discussion thread on the repository.

📄 License

DUMEdb is licensed under the MIT License. Built for high-performance deterministic agentic computing.