Agentic Cognitive Core: Multi-Agent Swarm Memory & Signal Routing Framework

Author: Elton Boehnen (boehnenelton2024@gmail.com)
BEJSON Specification: 104a / 104db Standard
MFDB Specification: Version 1.3.1
Project Repository: Cognitive_Core

1. Overview & System Description

Agentic Cognitive Core is an enterprise-grade, lightweight, state-durable multi-agent cognitive architecture and signal-routing framework designed specifically for autonomous AI agent swarms and long-running project orchestrations. Built on top of the strict BEJSON (Boehnen-Elton JSON) 104a / 104db schema standard and MFDB (Multi-File Database v1.3.1) specification, this framework enables modular, fault-tolerant, and stateful multi-LLM workflows across local, cloud, and mobile execution environments (such as Termux/Android).

In traditional LLM agent patterns, memory is volatile and inter-agent communication is either locked into monolithic Python runtimes or prone to unhandled race conditions during context-window overflows. Agentic Cognitive Core addresses these limitations by introducing a decoupled, dual-tier memory layer combined with an event-driven signal bus and a resilient multi-provider LLM unified prompter.

                  +-------------------------------------------------------+
                  |               Unified Web Dashboard (GUI)             |
                  |                (agent_flow_app.py - Flask)            |
                  +---------------------------+---------------------------+
                                              |
                                              v
                  +-------------------------------------------------------+
                  |         Multi-Provider Unified Prompter v2.0          |
                  |       (unified_prompter.py - Gemini/Groq/OR/HF)      |
                  +---------------------------+---------------------------+
                                              |
                                              v
+-----------------------------------------------------------------------------------+
|                            Cognitive Core Engine & Libraries                      |
|  +-----------------------------------+     +-----------------------------------+  |
|  |     lib_bejson_agentic_core       |     |      lib_bejson_agentic_deploy    |  |
|  |   (Session State & Signals)       |     |   (Scale-to-Zero Local Runtime)   |  |
|  +-----------------+-----------------+     +-----------------+-----------------+  |
|                    |                                         |                    |
|                    +--------------------+--------------------+                    |
|                                         |                                         |
|                                         v                                         |
|  +-----------------------------------------------------------------------------+  |
|  |                       MFDB Manifest (104a.mfdb.bejson)                      |  |
|  |                       Agentic Cognitive Core Schema                        |  |
|  +--------------------------------------+--------------------------------------+  |
|                                         |                                         |
|     +-----------------------------------+-----------------------------------+     |
|     |                                                                       |     |
|     v                                                                       v     |
|  +----------------------------------+     +----------------------------------+    |
|  |        Entity Memory DBs         |     |      Signal & Workflow DBs       |    |
|  |  - agent_profile.bejson          |     |  - signal_dispatch.bejson        |    |
|  |  - episodic_memory.bejson        |     |  - task_queue.bejson             |    |
|  |  - semantic_memory.bejson        |     |  - audit_log.bejson              |    |
|  |  - working_memory.bejson         |     |  - feedback_loop.bejson          |    |
|  |  - state_snapshot.bejson         |     |  - connection_graph.bejson       |    |
|  +----------------------------------+     +----------------------------------+    |
+-----------------------------------------------------------------------------------+

Core Value Propositions & Architectural Pillars

Durable, Scale-to-Zero Session Lifecycle: Agents operating within this framework are not required to remain resident in system memory. State snapshots and current workflow steps are written directly to disk using atomic BEJSON operations (lib_bejson_agentic_core.py and lib_bejson_agentic_deploy.py). An agent can execute a single turn, persist its updated state, scale down to 0% CPU/RAM, and resume seamlessly when an asynchronous signal is emitted.
Decoupled Inter-Agent Signal Routing: Communication between agents is managed through an asynchronous event queue (signal_dispatch.bejson and AgentSignal). Signals carry targeted session IDs, signal types (e.g., DATA_REQUEST, signal_leaks_resolved), and arbitrary JSON payloads. Agents poll for unconsumed signals without blocking thread execution.
Multi-Provider Unified Intelligence Pool (v2.0): The unified_prompter.py orchestrator abstracts LLM providers (Google Gemini, Groq, OpenRouter, and HuggingFace Inference API) behind a single unified CLI interface. It features automated API key rotation, dynamic model toggling, automatic thinking-token extraction, and Google Search grounding toggles.
10-Entity Cognitive Memory Architecture: The framework organizes memory across 10 specialized BEJSON entity files governed by a master MFDB manifest (104a.mfdb.bejson):
- AgentProfile: Identity, system roles, and status of swarm agents.
- EpisodicMemory: Time-bound records of past agent executions and experiences.
- SemanticMemory: Factual knowledge graphs and learned concept mappings.
- WorkingMemory: Short-term task context buffers with expiration timestamps.
- SignalDispatch: History and queue of inter-agent signals.
- TaskQueue: Actionable jobs derived from inbound signals.
- StateSnapshot: Point-in-time state recovery data for fault-tolerant rollback.
- FeedbackLoop: Quantitative and qualitative evaluation metrics to tune prompt weights.
- ConnectionGraph: Topology of multi-agent networks and relational entity graphs.
- AuditLog: System-level tracing for operational security and execution debugging.
Visual Operational Dashboard (Flask GUI): A web-based interface (GUI/agent_flow_app.py) provides real-time monitoring of active agent sessions, unconsumed inter-agent signals, manually triggered state transitions, and interactive signal dispatching.

2. User Guide & Quickstart

Prerequisites

Python: Python 3.9+ (Python 3.14+ fully verified).
Dependencies: Standard Python library (json, pathlib, uuid, argparse, time, random) plus requests and Flask.
Environment API Keys: Secure environment variables stored in .env configurations or exported in your shell:
- GEMINI_KEY_1 through GEMINI_KEY_21
- GROQ_KEY_1 through GROQ_KEY_4
- OPENROUTER_KEY_1 through OPENROUTER_KEY_2

Standard Directory Structure

/storage/emulated/0/Labortory/AI Tools/Cognitive_Core/
├── Cognitive_Core/
│   ├── 104a.mfdb.bejson            # Master MFDB Database Manifest
│   └── data/                       # BEJSON Entity Storage Databases
│       ├── agent_profile.bejson
│       ├── audit_log.bejson
│       ├── connection_graph.bejson
│       ├── episodic_memory.bejson
│       ├── feedback_loop.bejson
│       ├── semantic_memory.bejson
│       ├── signal_dispatch.bejson
│       ├── state_snapshot.bejson
│       ├── task_queue.bejson
│       └── working_memory.bejson
├── GUI/
│   ├── agent_flow_app.py           # Flask Monitoring Dashboard
│   └── templates/
│       └── dashboard.html          # Web Interface UI Template
├── lib/
│   ├── lib_bejson_agentic_core.py   # Core Session & Signal Operations
│   ├── lib_bejson_agentic_deploy.py # Scale-to-Zero Deployment Wrappers
│   └── lib_mfdb_agent_core.py      # Alias API for MFDB Ecosystem
├── context.bejson                  # Project Standing Context & Purpose
├── mfdb_agent_coordinator.py       # Long-Running Workflow Coordinator
├── mfdb_agent_signal.py            # CLI Signal Dispatcher Utility
├── test_cognitive_core.py          # Pytest Validation Suite
└── unified_prompter.py             # Multi-Provider Orchestrator CLI

Installation & Initialization

Navigate to the project directory:

cd "/storage/emulated/0/Labortory/AI Tools/Cognitive_Core"

Run the test suite to ensure all memory structures and module dependencies are valid:
```
pytest
```
Expected Output: 3 passed in 0.50s

Step-by-Step Usage Examples

Scenario A: Using the Unified Prompter CLI

The unified prompter lets you issue queries across multiple AI backends with automatic rotation and fallback.

Submit a query to an active provider:

python3 unified_prompter.py --service gemini "Explain the advantages of BEJSON over standard JSON."

Prompt with automatic provider selection (Random Pool Dispatch):

python3 unified_prompter.py "Synthesize a strategy for multi-agent task distribution."

Override the model ID and write output directly to disk:

python3 unified_prompter.py --service openrouter --model "liquid/lfm-2.5-1.2b-thinking:free" "Draft a Python microservice" --output output.txt

Inspect the Intelligence Pool Registry status:
```
python3 unified_prompter.py --list
```

Toggle service or model availability:

# Toggle service on or off
python3 unified_prompter.py --toggle-service groq

# Set a single service as the exclusive primary provider
python3 unified_prompter.py --set-primary gemini

Scenario B: Long-Running Agent Session & Signal Passing

The coordinator demonstrates stateful onboarding workflows (START -> AUDITING -> PAUSED -> STAGING -> COMPLETED).

Initialize a new onboarding session:

python3 mfdb_agent_coordinator.py --init "https://github.com/example/repo"

Output:

[+] Initialized Session: e4a3b8c1-1234-5678-9abc-def012345678
[*] Processing Session: e4a3b8c1-1234-5678-9abc-def012345678 | Step: START
[*] STEP 1: PULLING - Delegating to GitHub Manager for https://github.com/example/repo
[+] Transitioned to AUDITING.

Advance the session step:

python3 mfdb_agent_coordinator.py --run "e4a3b8c1-1234-5678-9abc-def012345678"

Output:

[*] Processing Session: e4a3b8c1-1234-5678-9abc-def012345678 | Step: AUDITING
[*] STEP 2: AUDITING - Running Policy Enforcer (leak_check)...
[!] LEAKS DETECTED. Pausing for human resolution.

Check session state (Notice it enters PAUSED state waiting for signal_leaks_resolved):

python3 mfdb_agent_coordinator.py --run "e4a3b8c1-1234-5678-9abc-def012345678"

Output:

[*] Processing Session: e4a3b8c1-1234-5678-9abc-def012345678 | Step: PAUSED
[*] STEP 3: PAUSED - Checking for 'signal_leaks_resolved' signal...
[-] No signal found. Agent staying dormant.

Emit the resolution signal via CLI:

python3 mfdb_agent_signal.py --sid "e4a3b8c1-1234-5678-9abc-def012345678" --type "signal_leaks_resolved" --payload '{"resolved_by": "Elton Boehnen"}'

Output:

[+] Signal Emitted: 9f8e7d6c-5432-10fe-dcba-9876543210fe

Resume and complete the onboarding flow:

python3 mfdb_agent_coordinator.py --run "e4a3b8c1-1234-5678-9abc-def012345678"

Output:

[*] Processing Session: e4a3b8c1-1234-5678-9abc-def012345678 | Step: PAUSED
[*] STEP 3: PAUSED - Checking for 'signal_leaks_resolved' signal...
[+] Signal received! Resuming...

Running it once more advances through STAGING to COMPLETED.

Scenario C: Launching the Flask GUI Dashboard

Start the local monitoring dashboard:

python3 GUI/agent_flow_app.py

Dashboard Endpoint: http://localhost:5007
Features:
- View live active agent sessions, steps, and pending signal requirements.
- Advance session steps via interactive buttons (Advance).
- Send direct signal events (Fix Leaks) to paused agents.
- Monitor unconsumed signals in the system inbox.
- Exposes REST webhook endpoint at /api/webhooks/signal for external event integration.

3. Technical Architecture & Component Details

Python Module Breakdown

File Path	Description & Primary Function
`lib/lib_bejson_agentic_core.py`	Core API for session CRUD (`bejson_agentic_session_create`, `load`, `update`) and signal management (`signal_send`, `poll`, `consume`). Implements atomic disk writes.
`lib/lib_bejson_agentic_deploy.py`	Execution environment wrapper (`deploy_local_runtime`). Handles scale-to-zero process spawning via subprocesses and tracks `BUSY`/`ERROR` state transitions.
`lib/lib_mfdb_agent_core.py`	Core API compatibility layer mapping `mfdb_agent_*` function signatures directly to the underlying BEJSON agent storage engine.
`unified_prompter.py`	Multi-LLM provider engine supporting Gemini, Groq, OpenRouter, and HuggingFace. Features fallback keys, error limits, thinking tag parsers, and registry management.
`mfdb_agent_coordinator.py`	State-machine orchestrator demonstrating long-running multi-step project onboarding with human-in-the-loop signal triggers.
`mfdb_agent_signal.py`	Command-line utility for emitting signal messages with custom JSON payloads directly into an agent's signal queue.
`GUI/agent_flow_app.py`	Web dashboard application powered by Flask. Bridges HTTP webhook requests with the backend BEJSON durable state system.
`test_cognitive_core.py`	Unit test suite validating framework import safety, MFDB 104a manifest structural integrity, and the existence of all 10 cognitive entity files.

BEJSON Schema Standards (104a & 104db)

The foundation of the system's memory model relies on BEJSON (Boehnen-Elton JSON), a structured data format optimized for deterministic parsing, field validation, and atomic record operations.

BEJSON 104a Specification

BEJSON 104a files represent clean single-entity or relational table structures. They enforce explicit field typing (string, integer, number, boolean, array, object).

Example - Cognitive_Core/104a.mfdb.bejson:

{
  "Format": "BEJSON",
  "Format_Version": "104a",
  "Format_Creator": "Elton Boehnen",
  "MFDB_Version": "1.3",
  "DB_Name": "Agentic_Cognitive_Core",
  "Records_Type": [ "mfdb" ],
  "Fields": [
    { "name": "entity_name", "type": "string" },
    { "name": "file_path", "type": "string" },
    { "name": "description", "type": "string" },
    { "name": "record_count", "type": "integer" },
    { "name": "schema_version", "type": "string" },
    { "name": "primary_key", "type": "string" }
  ],
  "Values": [
    ["AgentProfile", "data/agent_profile.bejson", "Core identity and state of individual agents", 2, "1.0", "agent_id"],
    ["SignalDispatch", "data/signal_dispatch.bejson", "Inter-agent communication and event triggers", 2, "1.0", "signal_id"]
  ]
}

BEJSON 104db Specification

BEJSON 104db allows multiple entity types to co-exist inside a single database file.

Field index 0 MUST be named exactly "Record_Type_Parent" (type string).
Every subsequent field definition must declare an explicit "Record_Type_Parent" property mapping it to its owner entity.
Rows store null for fields that do not belong to their specific entity type.

Entity Schemas & Memory Subsystems

The framework's memory is divided into 10 structured entities:

AgentProfile (data/agent_profile.bejson)
- Fields: agent_id (string), name (string), role (string), status (string), created_at (string).
- Serves as the central registry of agents in the cognitive cluster.
WorkingMemory (data/working_memory.bejson)
- Fields: session_id (string), agent_id_fk (string), active_context_tags (array), ephemeral_state (object), expires_at (string).
- Maintains the immediate, short-term task context for active agent loops.
EpisodicMemory (data/episodic_memory.bejson)
- Fields: memory_id (string), agent_id_fk (string), event_type (string), summary (string), raw_interaction (object), timestamp (string).
- Records historical experiences and past task execution sequences.
SemanticMemory (data/semantic_memory.bejson)
- Fields: concept_id (string), subject (string), predicate (string), object (string), confidence (number), updated_at (string).
- Stores general knowledge, facts, and learned domain rules.
SignalDispatch (data/signal_dispatch.bejson)
- Fields: signal_id (string), sender_id_fk (string), receiver_id_fk (string), signal_type (string), payload (object), status (string), dispatched_at (string).
- Acts as the event queue for asynchronous inter-agent signaling.
TaskQueue (data/task_queue.bejson)
- Fields: task_id (string), assigned_agent_fk (string), priority (integer), description (string), status (string), created_at (string).
- Tracks actionable task items derived from human input or agent signals.
StateSnapshot (data/state_snapshot.bejson)
- Fields: snapshot_id (string), session_id_fk (string), serialized_state (object), created_at (string).
- Supports disaster recovery and step rollback for complex orchestrations.
FeedbackLoop (data/feedback_loop.bejson)
- Fields: feedback_id (string), target_action (string), score (number), notes (string), created_at (string).
- Enables continuous self-improvement and optimization of agent responses.
ConnectionGraph (data/connection_graph.bejson)
- Fields: edge_id (string), source_id (string), target_id (string), relationship_type (string), weight (number).
- Maps topologies between agents or semantic knowledge nodes.
AuditLog (data/audit_log.bejson)
- Fields: log_id (string), actor_id (string), action (string), result (string), timestamp (string).
- Logs system events, security operations, and execution history.

Inter-Agent Communication Mechanics

The signaling engine operates on a push-poll model designed for loose coupling and high reliability.

+------------------+                    +-------------------------+                    +------------------+
|  Agent Alpha     |                    |  Signal Dispatch Queue  |                    |  Agent Beta      |
|  (Sender)        |                    | (signal_dispatch.bejson)|                    |  (Receiver)      |
+--------+---------+                    +------------+------------+                    +--------+---------+
         |                                           |                                          |
         | 1. send_signal(sid, "TYPE", payload)     |                                          |
         +------------------------------------------>|                                          |
         |                                           |                                          |
         |                                           | 2. poll_signals(sid, "TYPE")             |
         |                                           |<-----------------------------------------+
         |                                           |                                          |
         |                                           | 3. Returns unconsumed matching signals   |
         |                                           |----------------------------------------->|
         |                                           |                                          |
         |                                           | 4. consume_signal(signal_id)             |
         |                                           |<-----------------------------------------+
         |                                           |                                          |
         |                                           | 5. Mark consumed = True                  |
         |                                           |                                          |

Signal Dispatch (bejson_agentic_signal_send): When an agent or user issues a signal, a new record is appended to the signal registry with consumed = False and an ISO-8601 UTC timestamp.
Signal Polling (bejson_agentic_signal_poll): Recipient agents query the registry using their assigned session_id and optional signal_type. The query filters for unconsumed signals.
Signal Consumption (bejson_agentic_signal_consume): Once processed, the receiver marks the signal's consumed attribute to True using atomic disk write operations, ensuring signals are processed exactly once.

Programmatic Python Integration

Developers can embed Agentic Cognitive Core directly into Python applications:

from pathlib import Path
import sys

# Add library path
LIB_DIR = Path("/storage/emulated/0/Labortory/AI Tools/Cognitive_Core/lib")
sys.path.append(str(LIB_DIR))

from lib_bejson_agentic_core import (
    bejson_agentic_session_create,
    bejson_agentic_session_load,
    bejson_agentic_session_update,
    bejson_agentic_signal_send,
    bejson_agentic_signal_poll,
    bejson_agentic_signal_consume
)

# 1. Spawn a new agent session
session_id = bejson_agentic_session_create(
    agent_name="DataSynthesizer",
    initial_step="ANALYZING",
    metadata={"dataset": "financial_q2.json"}
)
print(f"Created Session: {session_id}")

# 2. Update session state to wait for validation
bejson_agentic_session_update(
    session_id=session_id,
    step="AWAITING_APPROVAL",
    status="PAUSED",
    pending_signals=["signal_approved"]
)

# 3. Simulate an external supervisor issuing an approval signal
bejson_agentic_signal_send(
    session_id=session_id,
    signal_type="signal_approved",
    payload={"approved_by": "SupervisorAgent"}
)

# 4. Agent polls for required signals
pending_signals = bejson_agentic_signal_poll(session_id, signal_type="signal_approved")

if pending_signals:
    for sig in pending_signals:
        print(f"Processing Signal {sig['signal_id']}: Payload = {sig['payload']}")
        # Mark signal as processed
        bejson_agentic_signal_consume(sig['signal_id'])
    
    # Resume agent activity
    bejson_agentic_session_update(
        session_id=session_id,
        step="PROCESSING",
        status="ACTIVE",
        pending_signals=[]
    )
    print("Session resumed successfully.")

4. Operational Best Practices & Troubleshooting

Operational Guidelines

Atomic File Operations: Always utilize bejson_core_atomic_write provided by the core libraries when modifying .bejson files to prevent write collisions in multi-threaded or multi-process environments.
Key Rotation in Unified Prompter: Ensure your API key files or environment variables include multiple valid credentials. The prompter automatically cycles through keys upon encountering rate limits (HTTP 429) or backend errors.
Scale-to-Zero Deployment: Use deploy_local_runtime() inside event loops or cron triggers. Since sessions persist state to disk, runtimes can terminate completely after every turn without losing progress.

Troubleshooting Common Issues

FileNotFoundError: Entity 'X' not registered in manifest
- Cause: The entity name being accessed is missing from Cognitive_Core/104a.mfdb.bejson.
- Resolution: Open Cognitive_Core/104a.mfdb.bejson and ensure the entity name and corresponding data/<entity>.bejson file path are correctly mapped in the Values array.
Pytest Failure / Import Errors
- Cause: Python path missing lib/ directory.
- Resolution: Ensure test scripts dynamically add lib/ to sys.path:
```
sys.path.append(str(Path(__file__).resolve().parent / "lib"))
```
Prompter Cooldown Triggered
- Cause: Exceeded the consecutive error limit (default: 3 errors) across all provided API keys.
- Resolution: Check network connectivity, verify API key validity, or wait for the cooldown timer (default: 5–15 minutes) to expire.

5. Commercial Credits & License Information

Agentic Cognitive Core is developed and maintained by Elton Boehnen.

Lead Architect & Author: Elton Boehnen
Contact Email: boehnenelton2024@gmail.com
Specification Standards: BEJSON 104a / 104db Standard, MFDB Version 1.3.1

All modules, library components, schemas, and documentation produced within this repository are explicitly credited to Elton Boehnen.

End of Documentation — Agentic Cognitive Core v1.0

Navigation Menu

Repository navigation

About

Repository files navigation

Agentic Cognitive Core: Multi-Agent Swarm Memory & Signal Routing Framework

1. Overview & System Description

Core Value Propositions & Architectural Pillars

2. User Guide & Quickstart

Prerequisites

Standard Directory Structure

Installation & Initialization

Step-by-Step Usage Examples

Scenario A: Using the Unified Prompter CLI

Scenario B: Long-Running Agent Session & Signal Passing

Scenario C: Launching the Flask GUI Dashboard

3. Technical Architecture & Component Details

Python Module Breakdown

BEJSON Schema Standards (104a & 104db)

BEJSON 104a Specification

BEJSON 104db Specification

Entity Schemas & Memory Subsystems

Inter-Agent Communication Mechanics

Programmatic Python Integration

4. Operational Best Practices & Troubleshooting

Operational Guidelines

Troubleshooting Common Issues

5. Commercial Credits & License Information

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Agents		Agents
Cognitive_Core		Cognitive_Core
GUI		GUI
docs		docs
images		images
lib		lib
.gitignore		.gitignore
OLD NAMES .MD		OLD NAMES .MD
README.md		README.md
auditreport.md		auditreport.md
bejson_project.json		bejson_project.json
context.bejson		context.bejson
mfdb_agent_coordinator.py		mfdb_agent_coordinator.py
mfdb_agent_signal.py		mfdb_agent_signal.py
test_cognitive_core.py		test_cognitive_core.py
unified_prompter.py		unified_prompter.py

Latest commit

History

Folders and files

Repository files navigation

Agentic Cognitive Core: Multi-Agent Swarm Memory & Signal Routing Framework

1. Overview & System Description

Core Value Propositions & Architectural Pillars

2. User Guide & Quickstart

Prerequisites

Standard Directory Structure

Installation & Initialization

Step-by-Step Usage Examples

Scenario A: Using the Unified Prompter CLI

Scenario B: Long-Running Agent Session & Signal Passing

Scenario C: Launching the Flask GUI Dashboard

3. Technical Architecture & Component Details

Python Module Breakdown

BEJSON Schema Standards (104a & 104db)

BEJSON 104a Specification

BEJSON 104db Specification

Entity Schemas & Memory Subsystems

Inter-Agent Communication Mechanics

Programmatic Python Integration

4. Operational Best Practices & Troubleshooting

Operational Guidelines

Troubleshooting Common Issues

5. Commercial Credits & License Information

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages