Mfdb_Agent: Authoritative Technical Manual v1.0

1. Introduction

Mfdb_Agent represents the evolution of the BEJSON Ecosystem agentic capabilities. Transitioning from simple, stateless conversational loops to durable, long-running coordinators, this project implements the 2026 Google ADK (Agent Development Kit) standards.

The primary goal of Mfdb_Agent is to manage complex workflows that span days or weeks—such as repository onboarding, security audits, and multi-stage code transformations—without losing context, even in volatile execution environments (e.g., Termux, Cloud Run, or local containers).

2. Core Architectural Pillars

2.1 Durable Memory Schemas (BEJSON 104)

Unlike standard agents that dump raw JSON into vector databases or rely on ephemeral chat history, Mfdb_Agent uses a structured, durable state layer. This layer is built on the MFDB (Multifile Database) v1.3.1 standard.

State Independence: The agent reasoning position is decoupled from the chat log.
Positional Integrity: Using BEJSON 104, state variables are stored in fixed positions for rapid, index-based access.
Persistence: All session data is stored on disk in Data/agent_session.bejson.
Context Preservation: Every step creates a checkpoint, meaning a container restart or crash will not impact the flow.

2.2 Event-Driven Dormancy (Signal Protocol)

To solve the challenge of idle time, Mfdb_Agent implements a Signal-File Protocol. When an agent requires external input (human approval, tool completion, webhook trigger), it transitions to a PAUSED status.

Dormancy: The agent process can terminate completely while waiting, consuming zero resources.
Signals: External systems emit signals by writing to Data/agent_signal.bejson.
Resumption: The coordinator wakes up, hydrates the session context, and applies a state_delta before continuing its reasoning chain.

2.3 Multi-Agent Delegation

To maintain high-quality reasoning, Mfdb_Agent uses a coordinator-worker pattern.

Coordinator: Manages the high-level state machine and workflow transitions.
Workers: Specialized sub-agents (Gemini, Groq, etc.) with narrow, tool-focused instructions.
Handoffs: Transitions are handled via the system switchboard, ensuring specialized knowledge is applied at each step.

3. Data Architecture (MFDB Structure)

3.1 Root Manifest: 104a.mfdb.bejson

The central registry for the Mfdb_Agent database.

Registers entities like AgentSession and AgentSignal.
Maintains referential integrity between metadata and data files.
Defines the Primary Keys for all associated data entities.

3.2 Session Entity: Data/agent_session.bejson

Tracks the lifecycle of every agentic flow.

Fields:
session_id: Unique UUID.
agent_name: The coordinator profile in use.
current_step: Current position in the state machine (e.g., START, AUDITING).
status: Lifecycle state (ACTIVE, PAUSED, COMPLETED, ERROR).
metadata: Object containing workflow-specific data (e.g., repo_url).
pending_signals: Array of signal types required to resume.
last_updated: ISO timestamp.

3.3 Signal Entity: Data/agent_signal.bejson

The inbox for inter-agent and external communication.

Fields:
signal_id: Unique identifier.
session_id_fk: Foreign key to the target session.
signal_type: The event name (e.g., signal_leaks_resolved).
payload: Data payload carried by the signal.
consumed: Boolean flag indicating if the signal has been processed.

4. Library Family: lib_bejson_agentic

The lib/ directory contains the formalized logic used across the ecosystem.

4.1 lib_bejson_agentic_core.py

The low-level API for interacting with the agent database.

bejson_agentic_session_create(): Initializes a new durable flow.
bejson_agentic_session_load(): Re-hydrates state from disk.
bejson_agentic_session_update(): Atomically updates checkpoints.
bejson_agentic_signal_send(): Emits an event to a session.
bejson_agentic_signal_poll(): Checks for unconsumed signals.

4.2 lib_bejson_agentic_deploy.py

High-level deployment and runtime management.

Handles Scale-to-Zero logic by triggering the coordinator on-demand.
Wraps subprocess execution to ensure isolation between agent steps.
Simulates the Agent Runtime environment within local infrastructure.

5. Cognitive Core: Advanced Intelligence Clusters

Located in Cognitive_Core/, these entities provide the agent with human-like memory and reasoning capacities.

Episodic Memory: Stores specific experiences and tool outputs as time-bound events. Includes importance scores for contextual retrieval.
Semantic Memory: Stores factual knowledge, learned concepts (e.g., BEJSON 104 Rules), and user preferences.
Working Memory: A high-speed context buffer for the current session, holding ephemeral tags and short-term state.
Signal Dispatch: Formalized routing for internal agent communication.
Task Queue: Manages atomic units of work generated by agent reasoning.
State Snapshot: Point-in-time recovery points for complex cognitive states.
Feedback Loop: Self-correction mechanism where past actions are evaluated and weighted.
Connection Graph: Maps relationships between concepts and agents, enabling complex multi-agent social structures.
Audit Log: System-level tracing for security, debugging, and policy enforcement.

6. Graphical Coordination: The Flask GUI

The dashboard at GUI/agent_flow_app.py provides a visual control plane.

Real-Time Visibility: Tables showing every active session and its current step.
Manual Control: Buttons to trigger Advance (forcing a state check) or Manual Signal (bypassing automated hooks).
Signal Tracking: Visualizes the Signal Inbox, showing which signals are pending and which have been consumed.
Webhook Gateway: The /api/webhooks/signal endpoint allows the local ecosystem to act as a production web environment.

7. Reference Workflow: System-Wide Project Onboarding

This workflow demonstrates the power of long-running coordination.

Phase 1: Initialization
Tool: mfdb_agent_coordinator.py --init
State: START
Phase 2: Ingestion
Action: Delegated to github_repo_manager.
State Transition: PULLING -> AUDITING.
Phase 3: Security Audit (The Pause)
Action: Runs leak_check.py.
If Leaks Found: Updates status to PAUSED, registers pending_signals=["signal_leaks_resolved"].
Dormancy: Agent process exits and waits.
Phase 4: Resumption
User Action: Scrubs credentials and emits signal via mfdb_agent_signal.py.
Signal Consumer: Coordinator detects signal, consumes it, and resumes.
Phase 5: Finalization
Action: Moves project to Buildrepos and updates projects_index.bejson.
State: COMPLETED.

8. Standards & Compliance

8.1 BEJSON Versioning

Manifests: Always BEJSON 104a.
Data Entities: Always BEJSON 104 for dense record storage.

8.2 Security Protocols

POL005 Adherence: All code movement must be preceded by a leak_check.py scan.
Credential Masking: Sensitive keys are never stored in agent_session.bejson, only references to the ~/.env vault.

8.3 Operational Mandates

Atomic Writes: All state updates MUST use the bejson_core_atomic_write pattern to prevent data corruption during power failures or container crashes.
Pascal_Case: All directory and entity naming follow the Pascal_Case convention with underscores.

9. Appendix: CLI Reference

Command	Description
python3 mfdb_agent_coordinator.py --list	Lists all durable agent sessions.
python3 mfdb_agent_coordinator.py --init	Starts a new onboarding flow.
python3 mfdb_agent_coordinator.py --run	Executes the current step for a session.
python3 mfdb_agent_signal.py --sid --type	Sends an external signal to a session.
python3 GUI/agent_flow_app.py	Launches the web dashboard (Port 5007).

*Technical Manual v1.0 | Created: 2026-05-14 | Format Creator: Elton Boehnen*

Mfdb_Agent: Durable Agent Ecosystem